Skip to content

upstream-notes.md

Latest commit

 

History

History
78 lines (63 loc) · 3.74 KB

upstream-notes.md

File metadata and controls

78 lines (63 loc) · 3.74 KB
Raw

Upstream notes — consolidation as a layer for append-only agent memory

This prototype was built against claude-mem, an excellent local memory plugin for Claude Code that distills each session into atomic observations. The notes below capture what an upstream contribution would need, so the technique can live inside a real memory system rather than as a read-only sidecar.

The measured figures here are from a personal memory store. Project names are anonymized to project-a … g; the shape of the data is the point, not the identities.

Why consolidate at all

An append-only observation store grows without bound, and a "most-recent-N" injection both costs more over time and silently drops older, still-relevant context. Consolidation adds the missing evolution loop:

digest(n) = merge( digest(n-1), { obs : obs.epoch > watermark(n-1) } )

keyed on (project, type), with a per-cell watermark for incremental, idempotent, resumable re-runs.

Hard prerequisites before a PR (not a sidecar)

  1. Open an issue / discussion first. Gauge maintainer interest and learn whether a consolidation design already exists.
  2. In-schema, not sidecar. This prototype writes a separate digests.db and reads the source DB directly. An upstream version must follow the host's schema/migration conventions and storage layout.
  3. Route the merge through the host's provider abstraction. This prototype shells out to claude -p. Upstream must use whatever provider/model the user has configured — no hardcoded CLI.
  4. Cross-platform paths. Use the host's path resolvers; never hardcode an absolute home path.
  5. Config, not constants. MAX_NEW_PER_RUN, the type set, and the digest key should be configurable.
  6. Tests + docs. Document the new tables, the watermark semantics, and when consolidation fires.

Suggested PR decomposition (each commit leaves the host working)

# Commit Scope
1 Schema migration digests table in-schema via host migrations
2 Fold engine loadCells + drain-mode + watermark
3 Provider routing merge via host's configured provider/model
4 Budget enforcement hard post-merge truncate (close the advisory-budget gap)
5 Read-side injection digests slot into the host's session-start context path
6 Config + tests + docs constants → settings; tests; documentation

Out of scope for a v1

  • Semantic sub-topic clustering over vector embeddings (a v2 — v1 ships project × type).
  • Scheduling when the fold fires (propose; let the maintainer place it).

Measured shape (token estimates, chars/4; anonymized)

project     observations   raw tokens   digest tokens   ratio
project-a          1640      587,602        4,288       137.0x
project-b           753      310,395        6,489        47.8x
project-c           507      190,597        6,054        31.5x
project-d           127       50,824        4,557        11.2x
project-e            46       21,437        3,555         6.0x
project-f            34       11,588        2,344         4.9x
project-g            29       11,046        4,091         2.7x   (floor)
─────────────────────────────────────────────────────────────
TOTAL              3136    1,183,489       31,378        37.7x

Digest size is roughly flat (≈2.3–6.5K tokens) across projects spanning 29 to 1,640 observations, because it is bounded by cells × budget. So the compression ratio scales with history depth: near a wash on a fresh project, two orders of magnitude on a deep one. A session-start read injects one project's block.