Real decay write-back + contradiction supersede + token budget + typed LLM errors (Q-1…Q-5)

[tcconnally]

Implements PROMPT 1 from the pre-submission fix plan — the MemoryAgent Track requirements that were claimed in docs but absent in code, plus one discovery that changed the approach (see "Engram backend" below).

Track-requirement fixes

• Q-1 — demo crash: MemoryEntry.id now defaults to "" (the handoff doc said this was already applied — it was not on the remote). The tools layer constructed entries without id and crashed Session 1 with a verified TypeError.
• Q-2 — "timely forgetting" is now real: _decay_confidence writes decayed confidence back (was a literal pass). New facts default to 0.9 so they can decay; 1.0 is pinned for explicitly verified facts. Age is measured from created_at so the write-back doesn't reset the decay clock. end_session reports and prints every decay (~ forgotten: "…" 90% → 20% (14d old)).
• Contradiction supersede (the differentiator): detect_contradictions() (same-category token-overlap) + supersede() — old fact demoted to 0.2 (below the 0.3 recall floor), new fact stored at 0.9. The demo announces it:

  🔄 Updating — I had "We use Pinecone for vector search" at 90% confidence from earlier; superseding it (now 20% — effectively forgotten).

• Q-3 — token-budgeted context: recall_context keeps highest-confidence memories within max_context_chars (default 8000, env-overridable) with an explicit truncation note. Compounding can no longer grow the prompt until the context window 400s.
• Q-4 — typed LLM errors: LLMError with status/retryable; 429/5xx/network retried with 1s/2s/4s backoff, 4xx fail fast. process_message returns a clean sentence instead of [LLM Error…] text, and _auto_store skips extraction on failure — error strings can never be persisted as memories.
• Q-5 — per-session counts: session_memories resets in start_session.

Engram backend: rewritten as direct SQLite (discovery)

The installed engram-rs (v0.5.0) exposes only engram serve — the CLI verbs the old backend shelled out to (store/recall/delete/health) don't exist, so the demo could never have run against the real binary. Per the fix plan's "update it via the CLI or direct DB access", the backend now reads/writes engram's own facts/facts_fts schema directly (stdlib sqlite3, WAL, FTS5 with operator-safe quoting, soft-invalidation forget, id-upsert for confidence write-back). An engram serve pointed at the same db file serves these memories over MCP/REST — same store, two access paths. Timestamps round-trip, so age-based decay has real ages.

Also fixed while verifying: get_project_context searched for the literal words "conventions"/"tech stack", which stored content never contains — now wildcard recall scoped by category, split by tags ("4 conventions found" in the demo, previously 0).

Verification (end-to-end, real store)

$ python -m pytest tests/ -q
23 passed
$ DASHSCOPE_API_KEY=test MEMORY_BACKEND=engram ENGRAM_DB_PATH=/tmp/demo.db python -m agent.main
  Memory health: ok
  Existing memories: 0 → 5 across sessions   (persistence)
  Project context recall: 4 conventions found
  🔄 Updating — I had "We use Pinecone…" … superseding it
  (LLM 401s degrade to clean messages; nothing error-shaped stored)

Tests cover: decay write-back values + forgotten floor + pinned-1.0 + fresh-facts, supersede demote/unrelated/identical cases, context budget keep-best/truncation-note, LLM error non-storage, FTS operator injection inertness, project isolation, and the engram round-trip with tags/timestamps. CI workflow added.

🤖 Generated with Claude Code