ai-memory v0.8.0

Migrating from v0.6.3.x to v0.6.4

v0.6.4 — quiet-tools ships with a collapsed default tool surface. This document is the operator’s guide to the change and the opt-out path for power users.

Forward note (v0.7.0): the numbers in this historical migration doc (5 core / 43 full / 38 unloaded) reflect the v0.6.4 surface. At v0.7.0 the equivalents are 7 core / 74 full / 66 unloaded — the original 5 grew to 7 with the always-on memory_load_family + memory_smart_load loaders, and the full surface grew to 73 with the v0.7 additions (recursive-learning, Agent Skills, Batman Forms 1-7, QW-1/2/3, enterprise-config #1146, etc.). See MIGRATION_v0.7.md for the v0.6.4 → v0.7.0 path and MIGRATION_QUICKSTART.md for tiered (non-technical / SME / DevOps) recipes.

What changed

ai-memory mcp now defaults to --profile core instead of advertising all 43 tools. Eager-loading harnesses (Claude Desktop, OpenAI Codex CLI, xAI Grok CLI, Google Gemini CLI) save ~4,700 input tokens of tool-schema prefix per request — a 76.4% reduction measured against cl100k_base, the BPE Claude / GPT use for input accounting.

The other 38 tools remain reachable. Three opt-up paths:

  1. Static profile — ai-memory mcp --profile graph|admin|power|full selects a wider family set at startup.
  2. Comma-list custom — ai-memory mcp --profile core,graph,archive registers exactly those families.
  3. Runtime expansion — call memory_capabilities --include-schema family=<name> from inside the agent loop. The host (e.g., Claude Code’s deferred-tools path) can register the returned schemas without restarting the MCP server.

memory_capabilities is always loaded regardless of profile (it’s the bootstrap surface for runtime expansion).

Action required for power users

If you depend on tools outside the 5 core (memory_store, memory_recall, memory_list, memory_get, memory_search), pick one of:

Option A — Reproduce v0.6.3 surface 1:1

ai-memory mcp --profile full

Or via env / config:

# bash / zsh
export AI_MEMORY_PROFILE=full

# config.toml
[mcp]
profile = "full"

Resolution order: CLI flag > AI_MEMORY_PROFILE env > [mcp].profile config > core default.

Option B — Pick a narrower profile that includes your tools

If you use Use profile
memory_kg_*, memory_link, memory_entity_* graph
memory_update, memory_delete, memory_promote, memory_pending_* admin
memory_consolidate, memory_auto_tag, memory_check_duplicate, memory_expand_query power
memory_archive_* core,archive (custom)

Option C — Recommended: keep core, opt up via memory_capabilities

import { AiMemoryClient, requireProfile } from "@alphaone/ai-memory";

const client = new AiMemoryClient({ baseUrl: "http://localhost:9077" });
await requireProfile(client, "graph");  // throws ProfileNotLoaded if missing

from ai_memory import AiMemoryClient, require_profile, ProfileNotLoaded

with AiMemoryClient(base_url="http://localhost:9077") as c:
    require_profile(c, "graph")  # raises ProfileNotLoaded if missing

Per-harness recommendations

Run ai-memory install <target> --apply (e.g. ai-memory install claude-desktop --apply; the installer is per-target subcommand-shaped, dry-run by default) after upgrading to write the v0.6.4 default config:

Harness Loading mode Recommended profile Reason
Claude Code Deferred (ToolSearch) core Already lazy; profile barely matters
Claude Desktop Eager core (default) Save ~4,700 prefix tokens/request
OpenAI Codex CLI Eager core (default) Same
xAI Grok CLI Eager core (default) Same
Google Gemini CLI Eager + cache penalty core (default) Save tokens AND avoid cache-bust

Diagnostics

ai-memory doctor --tokens reports per-family + per-profile token cost using the static schema-size table compiled into the binary. Useful for:

ai-memory doctor --tokens                       # human-readable
ai-memory doctor --tokens --json                # structured
ai-memory doctor --tokens --raw-table           # full per-tool dump
ai-memory doctor --tokens --profile graph       # hypothetical profile

ai-memory audit show --capability-expansions reads the new audit_log SQLite table (schema v20) populated by memory_capabilities --include-schema calls. Useful for fleet operators verifying which agents are expanding which families.

NHI guardrails phase 1

v0.6.4 adds an opt-in per-agent capability allowlist. Default: gate disabled (Tier-1 single-process semantics, every caller may expand any family). Operators opt in by writing the table:

[mcp.allowlist]
"alice"          = ["core", "graph"]
"ai:claude-code" = ["full"]
"*"              = ["core"]

Pattern resolution: exact match wins; otherwise longest-prefix; otherwise the "*" wildcard. No-agent-id callers fall through to the wildcard rule.

Every memory_capabilities --include-schema call (grant or deny) is recorded in audit_log for compliance review.

What did not change