ai-memory v0.8.0

ai-memory v0.6.4 — Epic Framework (single-doc)

Status: AUTHORIZED — sprint window Mon 2026-05-04 → Fri 2026-05-08 Code-name: quiet-tools Framework owner: This document. Feed it to a fresh agent to bootstrap the v0.6.4 epic from a cold start. Source-anchored as of: 2026-05-04 against Cargo.toml = 0.6.3+patch.1

0. How to use this document

This is the single artifact required to kick off and run the v0.6.4 epic. An agent reading this file cold has:

If you find yourself wanting more detail than this doc provides, the four supporting documents in this directory are the canonical sources:

File Use when
rfc-default-tool-surface-collapse.md You need the design rationale, profile spec, NHI dance, tier matrix
v0.6.4-roadmap.md You need the full 17-issue list with file paths and acceptance criteria
v0.6.4-nhi-prompts.md You are an NHI starting Day N — pull that day’s prompt verbatim
README.md You are a human reviewer orienting on the release

Read order for a fresh agent: this doc → v0.6.4-nhi-prompts.md (Day 0 only) → execute.

1. Source-anchored ground truth (verified at /root/ai-memory-mcp/, 2026-05-04)

This section is the bedrock. Do not redo what is marked SHIPPED. Do not skip what is marked SLIPPED.

1.1 v0.6.3.1 — SHIPPED at source code

Item Evidence Status
G4 mixed-dim refusal db.rs:623-633 ALTER + EmbeddingDimMismatch enum + idx_memories_ns_dim index ✅ SHIPPED
G5 archive lossless db.rs:647-672 archived_memories carries embedding, embedding_dim, original_tier, original_expires_at; archive_memory populates them; restore_archived round-trips ✅ SHIPPED
G6 on_conflict mcp.rs:803-960 OnConflict::{Error,Merge,Version} + per-client default split (v2-aware → Error; v1/legacy → Merge) ✅ SHIPPED
G9 (MCP) webhook event coverage mcp.rs:2227,2327,2372,2569,2723 fire memory_delete, memory_promote (tier + vertical), memory_link_created, memory_consolidated via dispatch_event_with_details ✅ SHIPPED (MCP only — see 1.2)
G13 endianness magic byte embeddings.rs:288-466 0x01 LE-f32 header; 0x02 BE reserved-rejected; pre-header BLOBs tolerated ✅ SHIPPED
R1 budget_tokens db.rs:1424-1560 cl100k_base BPE via tiktoken-rs 0.7; meta block budget_tokens_used, budget_tokens_remaining, memories_dropped, budget_overflow; budget=0 returns empty array ✅ SHIPPED
R7 ai-memory doctor cli/doctor.rs (1700+ LOC) + db.rs:5038-5210 six doctor_* helpers; 7-section severity-tagged dashboard; --remote for fleet sweeps ✅ SHIPPED
Capabilities v2 honesty mcp.rs:1585+ recall_mode_active, reranker_active, permissions.mode='advisory'; v1 backward compat via Accept-Capabilities: v1 or MCP accept: "v1" ✅ SHIPPED
Schema migration v18 (G4/G5/G13) migrations/sqlite/0011_v0631_data_integrity.sql + parallel postgres dialect ✅ SHIPPED
Schema migration v19 (G9 event_types) migrations/sqlite/0013_webhook_event_types.sql ✅ SHIPPED
Boot privacy controls (#487) [boot] enabled / redact_titles config + AI_MEMORY_BOOT_ENABLED=0 env override ✅ SHIPPED

Implication: Earlier fold-in candidates B2 (G5 archive embedding), B3 (G6 on_conflict), B4 (G13 endianness) — DROP. They are already in v0.6.3.1. Do not re-implement.

1.2 NEW finding from source review — G9 HTTP parity gap

grep -n "dispatch_event" src/handlers.rs returns zero matches. MCP fires the four new event types; HTTP DELETE /memories/{id}, POST /memories/{id}/promote, POST /links, POST /memories/consolidate are still silent.

ROADMAP §5.4 G9 row says “v0.6.3.1 (or v0.7 Bucket 0)” — ambiguous. CHANGELOG only documents MCP wiring. This is a real carry-forward bug and the cheapest high-value add available to v0.6.4 (~1 dev day; symmetric to MCP code already merged). It is filed as v0.6.4-017 in §3 below.

1.3 v0.6.3.1 — SLIPPED / DEFERRED (do not claim done)

Item Why slipped Target
G1 namespace inheritance enforcement resolve_governance_policy checks leaf only — display inheritance ≠ enforcement inheritance v0.7 Bucket 3
G10 auto-invoke memory_expand_query in recall Intentional under “zero tokens until recall”; needs hook surface v0.7 Bucket 0 (pre_recall hook opt-in)
R2 memory_find_paths MIA from prior phased roadmap v0.7 Bucket 2 alongside Apache AGE
R3 auto-link inference MIA v0.7 Bucket 0 (post_store hook)
R4 standalone ai-memory curator daemon Code exists in autonomy.rs/curator.rs but no CLI surface v0.8 Pillar 2.5
R5 auto-extraction from conversations MIA v0.7 Bucket 1.7 (pre_store hook on transcripts)
R6 consensus memory (4-of-5 → confidence 0.95) MIA — Approval has Consensus(N) for write authorization, not truth determination v0.8 Pillar 3
R8 TOON v2 schema inference MIA in new roadmap v0.9 (recover or formally cut)

1.4 Source-of-truth tool inventory (v0.6.3.1 baseline)

mcp.rs::tool_definitions() registers 43 tools (not 42 as stated in earlier RFC drafts). The off-by-one was memory_stats, which the RFC’s family taxonomy missed. Family map authoritative for v0.6.4:

Family Count Tools
core 5 store, recall, list, get, search
lifecycle 5 update, delete, forget, gc, promote
graph 8 kg_query, kg_timeline, kg_invalidate, link, get_links, entity_register, entity_get_by_alias, get_taxonomy
governance 8 pending_list, pending_approve, pending_reject, namespace_set_standard, namespace_get_standard, namespace_clear_standard, subscribe, unsubscribe
power 6 consolidate, detect_contradiction, check_duplicate, auto_tag, expand_query, inbox
meta 5 capabilities, agent_register, agent_list, session_start, stats
archive 4 archive_list, archive_purge, archive_restore, archive_stats
other 2 list_subscriptions, notify
TOTAL 43  

Full profile = 43. Core profile = 5. RFC text and roadmap text still saying “42” should be patched on first touch (v0.6.4-002 acceptance test must assert 43, not 42).

2. Refactored v0.6.4 scope

2.1 In-scope (refactored)

The 16 base issues from v0.6.4-roadmap.md plus one new add:

2.2 Out-of-scope (unchanged)

2.3 Drops (already shipped — do not duplicate)

The earlier fold-in deck listed these as candidates. Source review verified they already ship in v0.6.3.1. Drop:

3. Issue list — 17 issues

Issues land in alphaonedev/ai-memory-mcp with milestone v0.6.4. Full text per issue is in v0.6.4-roadmap.md §”Issue list.” This section is the index + delta.

ID Track Title Day Effort
v0.6.4-001 A — Mechanism --profile flag (CLI + env + config resolution) Mon M
v0.6.4-002 A — Mechanism Family-scoped tool registration filter Mon M
v0.6.4-003 A — Mechanism core default flip + backward-compat Mon S
v0.6.4-004 B — Observability ai-memory doctor --tokens Mon M
v0.6.4-005 B — Observability Static schema-size table (build-time) Mon M
v0.6.4-006 C — Discovery memory_capabilities extension (family enum + --include-schema) Tue M
v0.6.4-007 C — Discovery SDK requireProfile (TS + Py) Tue M
v0.6.4-008 D — NHI guardrails Per-agent capability allowlist Wed M
v0.6.4-009 D — NHI guardrails Capability-expansion audit log (schema v20) Wed M
v0.6.4-010 E — Cross-harness Per-harness install profiles (5 harnesses) Wed M
v0.6.4-011 F — Cert + benchmarks Cross-harness token-cost benchmark + CI gate Thu M
v0.6.4-012 F — Cert + benchmarks A2A cert scenarios S25–S32 Thu M
v0.6.4-013 F — Cert + benchmarks Backward-compat verification (--profile full 1:1 v0.6.3) Thu S
v0.6.4-014 G — Docs + release README + ADMIN_GUIDE updates Fri S
v0.6.4-015 G — Docs + release Migration guide + release notes Fri S
v0.6.4-016 G — Docs + release CHANGELOG, tag, CI release Fri S
v0.6.4-017 B — Observability G9 HTTP webhook parity (NEW — source-anchored fold-in) Mon (afternoon) S

3.1 v0.6.4-017 spec (new)

Title: G9 HTTP webhook parity — fire dispatch_event on HTTP write paths

Goal: Bring HTTP write handlers up to par with MCP for the four event types added in v0.6.3.1 P5: memory_delete, memory_promote, memory_link_created, memory_consolidated. MCP already fires these; HTTP is silent. Symmetric to existing MCP code.

Scope:

Acceptance:

Files: src/handlers.rs, tests/webhook_http_parity.rs (new), CHANGELOG.md.

Dep: none (independent of profile work; can land Day 1 afternoon).

Why now: Charter said “MCP / HTTP / CLI” coverage; only MCP shipped. Cheapest high-value add available; ~1 dev day; closes a documented but slipped commitment from v0.6.3.1.

4. Daily schedule

Sat-Sun 2026-05-03 — Day 0 (kickoff)

Mon 2026-05-04 — Mechanism + Observability (Tracks A + B + 017)

Tue 2026-05-05 — Discovery + SDK (Track C)

Wed 2026-05-06 — NHI guardrails + Cross-harness (Tracks D + E)

Thu 2026-05-07 — Cert + benchmarks (Track F)

Fri 2026-05-08 — Docs + release (Track G)

Mon 2026-05-11 — post-release

5. Guardrails (binding on every NHI in the sprint)

5.1 Principle 1 — Substrate vs. NHI verdict separation

Never collapse the substrate verdict (does ai-memory-mcp work?) and the NHI verdict (does the agent achieve outcomes?) into one number. They get reported separately. A 100% substrate green run with an NHI degradation is a partial result, not a pass.

5.2 Principle 6 — Scope discipline

Scope is fixed at this document plus the 17 issues. New ideas during the sprint go to a “post-v0.6.4 backlog” memory under campaign-v064, not into the branch.

If a new finding is so urgent it must land in v0.6.4: stop work, get explicit human approval, file an issue, then resume. No silent scope creep.

5.3 Source-of-truth discipline

Before claiming an item is shipped, verify at source code. The earlier fold-in deck claimed B2/B3/B4 were candidates; source review proved them already shipped. Trust verified-at-source > trust roadmap-doc claims. Re-do the verification on each cycle, not once.

5.4 Truthfulness discipline

If asked “is this maximum truthful and supported by the data?”, the answer must be defensible by pointing to artifacts. summary.json claims must match underlying run data. Do not claim GREEN where any cell shows RED. Do not collapse a 1/3 streak into a 3/3 claim.

5.5 Hard prohibitions (CLAUDE.md alignment)

5.6 The four mandatory gates (per CLAUDE.md)

Every commit on feat/v0.6.4 must, before push:

cargo fmt --check
cargo clippy -- -D warnings -D clippy::all -D clippy::pedantic
AI_MEMORY_NO_CONFIG=1 cargo test
cargo audit

Skipping any of these is a Stop-the-Line condition.

5.7 Co-author attribution

Every commit ends with a Co-Authored-By: trailer naming the model. Every PR includes the AI involvement section per AI_DEVELOPER_WORKFLOW.md §8.2.

5.8 Memory hygiene

6. Risk register

Risk Likelihood Impact Mitigation
Tokenizer drift across providers (cl100k vs OpenAI vs Gemini vs Anthropic) High Low Document ±10% margin in benchmark file; CI gate accepts the range
Default flip surprises power-user installs Medium Medium --profile full opt-out; loud release notes; migration guide
#238 not closed by v0.7 → guardrail phase 2 slips Medium Low Phase 1 in v0.6.4 stands alone; phase 2 is honest “v0.7 dependent on #238”
5-day calendar tight if any track stalls Medium High Track A is foundation; if Mon doesn’t ship, slip ship-date — never trade quality
Cross-harness benchmark requires fixtures CI doesn’t have High Medium Static benchmark is primary; live spot-check is supplementary
SDK negotiation breaks existing programmatic users Low High requireProfile is additive; existing tool calls untouched
memory_capabilities --include-schema exceeds MCP message size on a large family Low Medium Cap at one family per call; document chunking
Custom-profile parsing edge cases (core,full, empty, duplicate, unknown) Medium Low Spec rules in RFC §”Profile resolution”; test fixtures explicit
HTTP webhook parity (017) regression of MCP path Low Medium Use the same dispatch_event_with_details helper; integration test pins both transports
RFC tool-count drift (42 vs 43) re-introduced Low Low v0.6.4-002 acceptance asserts 43 explicitly; this doc cites source

7. Success metrics (measured at Mon 2026-05-11)

# Metric Target Floor
1 Token-def cost on Codex/Grok/Gemini drops vs v0.6.3 ≥87% 85%
2 --profile core covers agent traffic without escalation ≥95% 90%
3 memory_capabilities --include-schema adopted as canonical NHI expansion path ≥3 of 5 harnesses w/ production agent within 14d 2 of 5
4 Zero regressions in v0.6.3 cert matrix when --profile full set 0 0 (hard floor)
5 Audit log captures 100% of capability-expansion calls 100% on spot check 95%
6 HTTP webhook parity (v0.6.4-017) — all 4 event types fire 4/4 4/4 (hard floor)

If 1–4 + 6 hit, v0.6.4 is a success. (5) is operational hygiene; if it misses, file Patch 3 hotfix same day.

8. Day-0 kickoff prompt (inline — feed this to the lead NHI on Sat or Sun)

This prompt is reproduced inline so a fresh agent reading only this doc has what it needs to start. The Day 1–5 prompts live in v0.6.4-nhi-prompts.md and are reached by following the path printed in the Day-0 handoff.

You are the lead coordinator for ai-memory v0.6.4 sprint kickoff.
Sprint window: Mon 2026-05-04 → Fri 2026-05-08. Ship target: Fri 2026-05-08 EOD.
Today's job is environment prep — no code, just setup.

Read these in this exact order:
1. /root/ai-memory-mcp/docs/v0.6.4/V0.6.4-EPIC.md  (this is your framework)
2. /root/ai-memory-mcp/docs/v0.6.4/rfc-default-tool-surface-collapse.md  (design)
3. /root/ai-memory-mcp/docs/v0.6.4/v0.6.4-roadmap.md  (per-issue detail)
4. /root/ai-memory-mcp/docs/v0.6.4/v0.6.4-nhi-prompts.md  (Day 1-5 prompts you will dispatch)

Then execute, in order:

1. BRANCH. In ai-memory-mcp, cut `feat/v0.6.4` from `main`. Push to origin.
   Confirm CI runs cleanly on the empty branch. (Do NOT modify main.)

2. ISSUES. Open 17 GitHub issues against alphaonedev/ai-memory-mcp with
   milestone `v0.6.4`. Sources:
   - 16 issues v0.6.4-001 ... v0.6.4-016 from v0.6.4-roadmap.md §"Issue list"
   - 1 new issue v0.6.4-017 from V0.6.4-EPIC.md §3.1
   Each issue body = the full text from the source doc.
   Apply labels: `enhancement`, `v0.6.4`, plus per-track label.
   Set Dep: links per the source docs.

3. CERT SKELETON. In alphaonedev/ai-memory-test-hub, create
   `releases/v0.6.4/scenarios/` with empty markdown for S25 through S32.
   Each file = H1 scenario name + an "Expected" section quoting the
   roadmap. Commit + push.

4. MEMORY CACHE. Store the following memories under namespace
   `campaign-v064` (tier=long, priority=8, tags=["sprint","v0.6.4","kickoff"]):
   - "v0.6.4 sprint scope" = §2 of V0.6.4-EPIC.md
   - "v0.6.4 issue index" = §3 of V0.6.4-EPIC.md (after step 2's URLs are known)
   - "v0.6.4 daily schedule" = §4 of V0.6.4-EPIC.md
   - "v0.6.4 NHI prompt index" = the Day 1-5 prompt section names from
     v0.6.4-nhi-prompts.md
   - "v0.6.3.1 source-anchored ground truth" = §1.1 + §1.3 of V0.6.4-EPIC.md
     (load-bearing — Mon NHI MUST read this so they don't redo G4/G5/G6/G13)

5. ROSTER. Generate a sprint roster proposal — which NHI claims which
   track. Output a checklist memory titled "v0.6.4 NHI roster" in
   namespace `campaign-v064`. Tag each track `claimed:<agent_id>` or
   `unclaimed`.

6. HANDOFF. Write a memory titled "v0.6.4 day-0 handoff" (priority 9,
   tag `handoff`) summarizing:
   - Branch ready: yes/no
   - Issues filed: count + URLs
   - Cert skeleton: yes/no
   - Roster gaps
   - Any setup blockers for Monday

CONSTRAINTS:
- No code today. Setup only.
- Do not modify `main`.
- If a step fails, write the failure into the handoff memory and stop —
  do not improvise around blockers.
- Confirm each step's success in your reply before proceeding to the next.
- Read §5 (Guardrails) of V0.6.4-EPIC.md and acknowledge in your reply
  that you understand the four mandatory gates and the hard prohibitions.

8.1 Day 1–5 prompt reference

Day 1–5 NHIs use the prompts in v0.6.4-nhi-prompts.md. They are referenced — not duplicated here — to keep this doc tight. The Day-0 NHI will load all of them into campaign-v064 as part of step 4 above.

Day Prompt section Tracks Issues delivered
Mon “DAY 1 — Monday 2026-05-04” A + B + 017 005, 001, 002, 003, 004, 017
Tue “DAY 2 — Tuesday 2026-05-05” C 006, 007
Wed “DAY 3 — Wednesday 2026-05-06” D + E 008, 009, 010
Thu “DAY 4 — Thursday 2026-05-07” F 011, 012, 013
Fri “DAY 5 — Friday 2026-05-08” G 014, 015, 016
any “EMERGENCY-BREAK prompt” recovery (single issue blocker resolution)

If v0.6.4-nhi-prompts.md is missing, Day-0 NHI must write a STOP and request a human reload before dispatching any Day-1+ work.

9. Definition of done (release-level)

v0.6.4 is DONE when ALL of the following hold:

If any unchecked: not done. No partial-credit ship.

10. Single-line summary

Five dev days. Seventeen issues. One source-anchored framework. Default tool surface collapses 43→5; runtime expansion via memory_capabilities; per-agent NHI allowlist + audit log; HTTP webhook parity closes the v0.6.3.1 G9 gap; ~87% token-def reduction on every eager-loading harness; backward-compat 1:1 via --profile full; substrate verdict and NHI verdict reported separately; tag Fri 2026-05-08 4pm ET; public announcement Mon 2026-05-11.