iai-mcp for Local Agent Memory Boundaries

The weak version of this article says iai-mcp gives AI assistants persistent memory. That is true but not enough.

The stronger article asks whether a local memory MCP should sit inside a Codex or Claude Code workflow at all. This is not a harmless convenience feature. The source says the system captures every turn verbatim, stores records locally, encrypts them at rest, consolidates them while idle, and serves a small relevant slice at session start.

That makes iai-mcp worth saving. It is a real architecture for local agent memory, with code-level boundaries: a TypeScript MCP wrapper, a Python daemon, a UNIX socket, LanceDB storage, capture hooks, doctor checks, encryption notes, and benchmark commands. The article should treat it as an operating decision, not as a memory headline.

The useful object is the boundary

A long-running coding agent has two different memory problems.

The first is policy memory: what the repo expects, how tests run, what files are off-limits. That belongs in AGENTS.md, CLAUDE.md, docs, or scripts.

The second is history memory: what the user already decided, which false lead was rejected, which deployment issue happened last week, which local preference keeps recurring. That is the gap iai-mcp tries to fill.

The boundary matters because the system is not just a note file. It installs hooks, captures turns, writes records, computes embeddings, maintains graph structure, and injects recall into future sessions. That should be a deliberate choice.

What the install actually creates

The README install path is simple:

git clone https://github.com/CodeAbra/iai-mcp.git
cd iai-mcp
bash scripts/install.sh

The installer script does real work. It creates a Python virtual environment, installs the Python package, builds the TypeScript MCP wrapper, symlinks the CLI to ~/.local/bin/iai-mcp, and on macOS registers a daemon through launchd.

The README prerequisites are also concrete: macOS, Python 3.11 or 3.12, Node.js 18+, Claude Code or Codex CLI as the MCP host, and about 500 MB of disk. Windows and Linux are listed as unsupported in the quick-start path, with a separate headless path for running the daemon elsewhere.

Hooks are the adoption decision

Without hooks, iai-mcp can expose memory tools, but it does not become ambient memory. The README says one command wires the capture and recall hooks:

iai-mcp capture-hooks install
iai-mcp capture-hooks status
iai-mcp capture-hooks uninstall

For Codex, the README gives:

iai-mcp capture-hooks install --target codex

The hooks are the point where a user should pause. The turn hook appends prompt and assistant-turn content to a session buffer. The stop hook rolls the buffer over for the daemon to drain. The session-start hook calls iai-mcp session-start and pipes the assembled memory prefix back into the host.

That is useful only if the user wants automatic capture. If the machine handles secrets, regulated customer work, or embargoed code reviews, automatic capture needs a policy before it needs enthusiasm.

The runtime shape is local but not magic

The README architecture is clear:

Claude Code  <--MCP-stdio-->  TypeScript wrapper  <--UNIX socket-->  Python daemon  <-->  LanceDB

The wrapper connects the MCP host to a Python daemon over a UNIX socket. The bridge source explicitly does not spawn the daemon itself. If the daemon is unreachable, it throws a daemon-unreachable error and points the user at launchd or install recovery commands.

That split is a good design for a memory service. The wrapper can advertise tools without owning the daemon's lifecycle. The daemon can keep state warm across host sessions. The operator has to own the daemon, socket, logs, and health checks.

The tool surface is broad

The TypeScript tool registry exposes twelve hot tools:

- `memory_recall`
- `memory_recall_structural`
- `memory_reinforce`
- `memory_contradict`
- `memory_capture`
- `memory_consolidate`
- `profile_get_set`
- `curiosity_pending`
- `schema_list`
- `events_query`
- `topology`
- `camouflaging_status`

That list tells you this is not only a key-value memory store. It has recall, capture, reinforcement, contradiction, consolidation, profile knobs, schema visibility, event audit, topology, and status tools.

For an article, the practical advice is simple: start read-only. Use recall and status first. Do not let an agent mutate memory until the user understands what is being captured and how to inspect or back it up.

Local-only still has a privacy model

The README says records are encrypted at rest with AES-256-GCM and that the key lives under ~/.iai-mcp. The security policy says the daemon listens on a UNIX socket only and assumes the host machine and MCP host are trusted.

That is a reasonable local tool model, but it is not a universal privacy guarantee. The same security policy says an attacker with local code execution as the user can read the key and unlocked store. The README also says normal conversation still goes to whatever LLM API the user's client uses.

So the correct line is:

Local storage reduces remote memory exposure.
It does not make captured prompts harmless.
It does not protect against a compromised local account.
It does not change the privacy posture of the active model provider.

That distinction belongs in the article.

Run doctor before trusting recall

The README describes iai-mcp doctor as a fourteen-check health report. The source backs that up with checks for daemon process liveness, socket status, lock health, orphan processes, state file validity, LanceDB readability, duplicate binders, crypto file state, lifecycle state, sleep status, heartbeat scanner, and idle source.

The adoption path should include:

iai-mcp doctor
iai-mcp daemon status
tail ~/.iai-mcp/logs/capture-$(date -u +%Y-%m-%d).log

A memory layer that silently fails is worse than no memory layer. It can inject stale context, miss important updates, or convince the user that a preference was remembered when it was never stored.

Benchmarks are a local test, not a headline

The README makes strong claims: high verbatim recall, low p95 latency, RAM bounds, and session-start token limits. It also includes commands to run benchmark harnesses:

python -m bench.verbatim
python -m bench.neural_map
python -m bench.memory_footprint
python -m bench.tokens
python -m bench.total_session_cost
python -m bench.trajectory
python -m bench.contradiction_longitudinal
python -m bench.longmemeval_blind

That is how the article should frame the numbers. The source provides harnesses. A team should run them on the target machine before treating performance as proven. The benchmark table is interesting; the adoption evidence is local output.

Where it fits in a Codex workflow

iai-mcp fits a solo or small-team workflow where repeated context loss is expensive:

- Long-running product work with recurring user preferences.
- Repeated debugging across sessions where false leads matter.
- Local-first agent experiments where memory should not be hosted remotely.
- Personal workflow memory, such as preferred test gates and repo habits.

It is less useful for short-lived tasks, clean CI-style agents, or repos where the correct state is already fully encoded in files. If AGENTS.md can answer the question, do not add a memory daemon for it.

Where to say no

Do not enable ambient capture on a machine where the user routinely pastes secrets, customer data, unreleased vulnerability reports, or legal material unless the data handling policy explicitly allows that local record.

Do not use it when several users share one OS account. The security model is single-user local.

Do not rely on it for cross-machine continuity. The README says there is no sync; backup is copying ~/.iai-mcp/ somewhere safe.

Do not adopt it if nobody will back up the key. The README is blunt: lose the key, lose the memories.

A cautious adoption plan

A safe trial is small:

Day 1: Install in a test account or non-sensitive local profile.
Day 2: Connect the MCP wrapper and run `iai-mcp doctor`.
Day 3: Install capture hooks for one host only.
Day 4: Run a few non-sensitive sessions and inspect capture logs.
Day 5: Test recall at session start.
Day 6: Run at least `bench.verbatim` and `bench.neural_map` locally.
Day 7: Decide whether automatic capture belongs in the real workflow.

The point is not to slow adoption. The point is to make memory a controlled system instead of a side effect.

Save the article as a local memory architecture guide. iai-mcp is useful because it turns cross-session agent memory into explicit machinery: hooks, wrapper, daemon, encrypted store, recall tools, health checks, and benchmark harnesses. It should not be sold as a generic memory upgrade.

Practical takeaway

Use iai-mcp only when durable local memory is worth the privacy and operations cost. Install it deliberately, enable hooks only after deciding what may be captured, run doctor and daemon checks, back up the encrypted store and key, reproduce the benchmarks locally, and keep secrets out of ambient capture.