← roadmap

intermem

improve priority P2 effort M wave 2

What it does: A stdlib-only Python pipeline (skill-driven, no MCP) that graduates stable auto-memory facts into curated AGENTS.md/CLAUDE.md. Confirmed in code: scanner.py parses Claude Code auto-memory markdown into entries; stability.py records per-entry SHA-256 hashes across session snapshots (stability.jsonl) and scores ‘stable’ at 3+ appearances; citations.py extracts/validates file & module paths with path-boundary safety (Path.resolve + is_relative_to), additive confidence (+0.3 valid, -0.4 broken, +0.2 for 5+ snapshots); dedup.py does 3-layer matching (exact SHA-256 on normalized line, difflib SequenceMatcher >=0.75, keyword-overlap >=0.60); promoter.py writes entries with markers; pruner.py removes from source; journal.py provides WAL-style crash-atomic promote/prune/demote. Phase 2A adds 14-day-grace time decay, stale_streak>=2 hysteresis before demotion, and auto-reactivation on reappearance, in metadata.db (SQLite, FKs + CHECK constraint). A ‘tidy’ subcommand extracts oversized MEMORY.md sections to topic files and detects stale counts; a SessionStart hook nudges when MEMORY.md exceeds 120 lines. Skills: synthesize, tidy (README’s ‘/intermem:validate’ is a CLI —validate flag, not a registered skill).

Rationale: intermem is a mature, carefully-engineered plugin (13 test files, documented crash recovery, timezone/regex-DoS/path-boundary safety, idempotent SQLite) that nails its core mission and aligns squarely with the 2026 SOTA preference for human-auditable, version-controlled, git-tracked memory over opaque auto-updating stores — the exact discipline the agent-memory survey literature and the project’s own ‘no MEMORY.md, use bd remember / git-committed docs’ mandate endorse. It does NOT warrant modernize/deprecate: the architecture is sound and the failure mode it solves (unbounded flat auto-memory) is real and well-handled. The one genuine frontier gap is that consolidation/dedup is purely lexical while the field (MemRouter embedding-gated memory, RAG-MCP, A-MEM/Mem0) has moved to embedding-aware consolidation — and a sibling plugin (intersearch) already supplies the embedding infra to close it without reinvention. That makes this an additive ‘improve’ (layer embeddings as an optional, non-default accuracy boost) rather than a rewrite. Driving SOTA trend: MemRouter / embedding-based memory gating + RAG-MCP embedding selection. P2/M because the lexical path works today, the win is accuracy on paraphrase (not correctness), and the embedding dependency is opt-in.

SOTA gap: All matching is lexical (SHA-256 exact-hash stability + difflib/keyword-overlap dedup). The 2026 agent-memory frontier (MemRouter embedding-gated memory selection; A-MEM/Mem0/Anatomy-of-Agentic-Memory consolidation discipline; RAG-MCP embedding gating) treats consolidation and dedup as embedding-aware operations. intermem misses paraphrased duplicates and under-counts stability when a fact is reworded across sessions (different hash = looks unstable), even though sibling intersearch already offers shared embedding_index/embedding_query infra it could consume. Secondary gap: the episodic/semantic/procedural memory-tier separation now standard in the literature — intermem only does the semantic-fact tier.

Redundancy: Low/healthy. Adjacent but distinct: intermem (auto-memory -> AGENTS.md graduation) vs interknow/qmd (durable pattern repo + local markdown search) vs interscribe (CLAUDE.md/AGENTS.md boundary enforcement) vs interwatch (doc freshness, declared optional companion) vs interdoc (AGENTS.md generation). intermem is the only write/consolidation pipeline FROM Claude Code auto-memory; the others read/search/generate/enforce. The integration.json correctly positions interwatch (citation freshness) and intercheck (pressure-triggered synthesis) as companions, not overlaps. Mild boundary overlap with interscribe on what belongs in AGENTS.md vs CLAUDE.md (intermem’s routing rule), but they are complementary (intermem promotes, interscribe polices placement).

Actions:

  • Add an optional embedding-gated layer: consume intersearch’s embedding_query to (a) collapse paraphrased near-duplicate stability hashes into one logical fact so reworded facts still accrue stability, and (b) add a semantic-similarity tier to dedup above the current keyword-overlap fallback. Keep lexical path as the deterministic, offline default so the auditable behavior is preserved.
  • Reconcile the README/plugin.json mismatch: README advertises ‘/intermem:validate’ but plugin.json registers only synthesize and tidy (validate is a CLI —validate flag). Either add a validate skill or correct the README so users aren’t misled.
  • Formalize the procedural-memory tier: many graduated facts are workflow/command conventions (the literature’s ‘procedural memory’). Add a routing/section convention (or tie into interknow) so workflow facts are promoted with provenance distinct from architectural/semantic facts, matching the episodic/semantic/procedural taxonomy.
  • Add a lightweight reliability check to the dedup/stability thresholds: the 0.75/0.60 cutoffs are hardcoded with no measured precision/recall. Capture promote/reject outcomes (the journal already logs decisions) and surface a calibration report so thresholds can be tuned from evidence rather than guessed.