feat: turnkey conversation-history compression (one-call episodic memory)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 9
- Forks
- 17
- Avg merge
- 21h 36m
- Merged PRs (30d)
- 22
Description
Summary
Make conversation-history compression a one-call, turnkey feature. Today the episodic store exists (add_episode_sync(episode_id, summary, metadata)), but the caller must produce the summary themselves and manually decide which turns to keep verbatim vs. compress. That friction is why the most universal pattern in real agents — growing chat history — does not actually benefit from contextweaver out of the box.
Why this matters (evidence)
A fleet-wide review of ~12 NOS GenAI agents found the context firewall fits almost none of them, because they fetch fresh retrieval per turn and keep only Q&A text in history (nothing large is re-carried). The pattern that is shared across nearly all conversational agents is unbounded or crudely-capped history:
dsi-av-chat-conv— history accumulates with no token cap/truncation found.dsi-km-agent— hard cap of "last 3 Q&A pairs" (memory.pyL133–138): bounds growth but hard-drops older context.- The same shape recurs in billing/customer conversational agents.
The right tool for this is episodic summarization — but it's currently too manual to be a drop-in. Closing this gap is the single highest-leverage way to make contextweaver useful in more repos.
Proposed API
A turnkey memory facade that owns the keep-recent / compress-old policy and (optionally) generates the summary:
mem = mgr.conversation_memory(
keep_recent_turns=4, # verbatim window
summarize_after_turns=8, # when to roll older turns into an episode
summarizer=None, # None => deterministic extractive summary; or a callable / LLM hook
token_budget=2000, # optional cap for the compressed history block
)
mem.add_turn(role="user", content=...)
mem.add_turn(role="assistant", content=...)
# returns recent turns verbatim + a single rolling episodic summary of older turns
history_block = mem.render_sync()
Internally this wraps the existing add_episode_sync / build_sync machinery; no new storage primitives required.
Acceptance criteria
- One call to obtain a bounded history block (recent verbatim + compressed older), with no caller-side summary production required.
- Deterministic default summarizer (no LLM dependency) so it works in deterministic pipelines; pluggable LLM summarizer hook (reuse the #384 path) for higher-fidelity rollups.
- Honors a
token_budgetfor the rendered history block. - Summarizer is told which turns it is compressing and must preserve entities/IDs referenced by later turns (round-trip test).
- Documented runnable example: a 30-turn conversation showing prompt-token growth flat-lining vs. the naive accumulate baseline.
Out of scope / relationship to other issues
- Not the context firewall (#403–406, #399, #402): those compress tool results; this compresses conversation turns.
- Complements #384 (LLM-assisted summarization) by reusing it as the optional summarizer backend.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the existing add_episode_sync and build_sync entry points, then inspect the #384 summarization path for a reusable hook. Define and test the conversation_memory facade, including bounded rendering, deterministic and pluggable summarization, token budgets, and preservation of entities and IDs. Finish with the requested runnable 30-turn example comparing growth with naive accumulation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- ai, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100