Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: align decay formula and §10 tool surface with shipped code
Victor Campos8555359fea5d
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 81f8c036..b7525bff 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -178,9 +178,17 @@ invariants below.| `memory_lint` | destructive | Rule-based + LLM contradiction findings → `wiki/_lint/`. || `memory_install_self_routing` | read-only | Return the canonical routing snippet for CLAUDE.md / AGENTS.md. |-All MCP tools carry `readOnlyHint` / `destructiveHint` annotations so-the calling agent can pick safely. Parameter aliases (`query|q|search`,-`workspace|ws`) absorb LLM verbal variance.+`memory_briefing`, `memory_explore` and `memory_install_self_routing`+post-date the original "narrow on purpose" cut (§10 of+`design-decisions.md`): briefing/explore separate the structured vs.+prose halves of "what's going on", and `memory_install_self_routing`+exists for the meta case where the agent must re-write its own routing+rules into a project's `CLAUDE.md` / `AGENTS.md`. The narrow-surface+discipline still holds — every new tool has to earn its slot — but the+v1 count is 11, not 10.++All MCP tools accept verbal-variance parameter aliases (`query|q|search`,+`workspace|ws`) so the calling agent can phrase arguments naturally.## CLI subcommand surface (17 commands)diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 44845a9e..535858d8 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -112,7 +112,7 @@ Adopt agentmemory's tier model **but** keep the surface narrow:| Tier | What it is | Lifetime | Decay ||---|---|---|---|| **Working** | Current session: last N observations, last user prompt, current files | Until session end | Drop on session end (kept in DB for forensics, but excluded from default recall) |-| **Episodic** | Per-session summaries with concept tags, files-touched, decisions made | 30 days hot, 180 days cold, then evict if cold-score < threshold | Salience × exp(-λΔt) + Σ(σ/days_since_access) - agentmemory's formula, validated |+| **Episodic** | Per-session summaries with concept tags, files-touched, decisions made | 30 days hot, 180 days cold, then evict if cold-score < threshold | `salience · exp(-λ · age_days) + σ · log(1 + access_count) · exp(-μ · days_since_access)`. Code of record: [`crates/ai-memory-store/src/decay.rs`](../crates/ai-memory-store/src/decay.rs). || **Semantic** | Distilled facts/preferences/architecture notes - the wiki pages themselves | Indefinite, supersedeable | Versioned in place: old `is_latest=false`, new `supersedes=old_id` || **Procedural** | Repeated patterns extracted from episodic clusters (`pattern` type with frequency ≥ 2) | Indefinite | Frequency-decay if not re-observed in N days |@@ -153,22 +153,21 @@ agentmemory has this informally (`/handoff` skill); we make it explicit from day## 10. MCP tool surface - narrow on purpose-basic-memory has ~25 tools, agentmemory has 53. Both have user confusion as a result. Ship **at most 10 v1 tools**:+basic-memory has ~25 tools, agentmemory has 53. Both have user confusion as a result. v1 ships 11 tools:| Tool | Purpose | Annotation ||---|---|---|-| `memory_remember` | Manual capture (rare) | destructive, idempotent |-| `memory_query` | Search + retrieve, auto-routed | read-only |-| `memory_recent` | Recent activity, optionally for-this-project | read-only |-| `memory_handoff_begin` | Mark session boundary, write handoff | destructive |-| `memory_handoff_accept` | Fetch+ack open handoff | destructive |-| `memory_forget` | Explicit user forget | destructive |-| `memory_session_summary` | Internal - used by stop hook | destructive (internal) |-| `memory_consolidate` | Internal - used by scheduler | destructive (internal) |-| `memory_lint` | Internal - used by scheduler | destructive (internal) |+| `memory_query` | Search + retrieve, FTS5 + optional hybrid RRF | read-only |+| `memory_recent` | Most-recently-updated `is_latest=1` pages for the project | read-only || `memory_status` | Health, counts, last-consolidation-at | read-only |--Internal tools are gated by `tools/list` annotation; agents see only the user-visible ones unless `expose=all` is set. Every tool has MCP `readOnlyHint`/`destructiveHint`/`idempotentHint` (basic-memory pattern; lesson from #818 - be careful with `bool | None` aliases on tool params).+| `memory_briefing` | Structured zero-LLM snapshot: 7d/30d windows, pending handoffs, recent pages, `_rules/` | read-only |+| `memory_explore` | LLM-composed prose digest over `memory_briefing`; degrades to JSON without a provider | read-only |+| `memory_handoff_begin` | Mark session boundary, write handoff | destructive |+| `memory_handoff_accept` | Fetch + ack the latest open handoff | destructive |+| `memory_consolidate` | LLM-driven page rewrite (`multi_page=true` for atomic fan-out) | destructive |+| `memory_forget_sweep` | Retention sweep (M8); soft-delete below cold threshold; `dry_run=true` previews | destructive |+| `memory_lint` | Rule-based + optional LLM contradiction findings → `wiki/_lint/<date>.md` | destructive |+| `memory_install_self_routing` | Returns the canonical CLAUDE.md / AGENTS.md routing block + per-agent filename hints | read-only |Tool param aliases: accept `query|q|search`, `project|workspace`, `dir|directory` - basic-memory's `AliasChoices` pattern works for LLM resilience.