dgenio / dgenio/contextweaver

feat: turnkey conversation-history compression (one-call episodic memory)

Open
#407 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

complexity:average priority:medium
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.py L133–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_budget for 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.