Skip to main content
Glama

MemAi

Paged memory for coding agents. MemAi distils your repository locally into a ~200-token project card plus a symbol manifest, then lets each session and subagent demand-page only the detail it needs, and resume after edits from a Merkle delta instead of re-reading files or consuming a model-written handoff. One stdio MCP server and one dependency-free CLI serve Claude Code, Codex, OpenCode, ZCode and DeepSeek Harness.

CI

v0.1.1 preview. The measured numbers below are real runs on one machine (Windows 11, Node 24.14); the compatibility matrix labels what was verified on an installed agent versus documented from vendor docs. npm package: memai-cli · CLI binary: memai · MCP binary: memai-mcp · store: .memai/ · root env: MEMAI_ROOT.

The problem, in one measurement

On one completed two-agent coding task (170 model steps, 32.8M tokens billed):

  • 98.3% of billed tokens were re-sent context, not new input;

  • 91.4% of prompt tokens were tool results — file reads, shell output, inspection dumps — each riding in the window for ~39 further steps;

  • 14.9% of tool-output bytes were byte-identical repeats.

Re-reading files is not the expensive part. Re-sending everything that was ever read is. See docs/evidence.md for the method and the counterfactual replay: keeping only the last 8 tool results inline would have cut prompt tokens 7.8× and cost −56% on that task.

Related MCP server: agent-project-intelligence

What MemAi does

Idea

In practice

One small card

memai card → stack, entrypoints, build/test commands, layout, conventions, paging rules. ~200 tokens, byte-stable, content-addressed.

One manifest

memai map → one line per file with LOC + top symbols, budget-capped. The agent knows what exists without reading it.

Demand paging

memai query returns ranked path:line snippets; memai fault materialises one symbol body; get file:<path> returns signatures, not bodies. Every response is token-counted and clamped to a hard budget.

Merkle deltas

memai diff --since <hash> returns added/changed/removed files plus symbol churn in ~100 tokens. A new session or a fresh subagent resumes from a version stamp.

A shared board

note/post/inbox/merge — append-only typed messages carrying page ids, never file bodies. Agents share state without model-written summaries or steering messages.

One integration surface

A stdio MCP server (memai-mcp) plus a CLI (memai). memai init writes the per-agent instruction blocks and config snippets.

Local-first: extraction runs on CPU/disk with zero model tokens and zero dependencies — no npm install, no embeddings, no server, no network.

Measured

14 tasks across four corpora, all self-contained in this repo: a generated 200-file API fixture, a real 288-file npm CLI (shipped with Node), MemAi itself (self-host), and the bundled DSH adapter. All numbers are reproducible from a fresh clone (node bench/bench.mjs); full method, per-task table and honest limits are in bench/RESULTS.md.

scenario (14 tasks)

input tokens

cost (off-peak)

A — grep + read the needed files

67,149

$0.010744

B — read + model-written summary handoff + re-read

78,774

$0.018707

C — card + curated paging plan

14,861

$0.002901

C* — card + paging + completion to 100% recall

21,958

$0.003966

  • 3.06× fewer input tokens than naive file reads (45,191 tokens saved across the 14 tasks), and 3.59× fewer than the summary-handoff workflow.

  • 4.7× cheaper in dollars than model-written handoffs (C* $0.003966 vs B $0.018707): one output token costs 200× a cache-hit input token, so writing prose is the expensive way to move facts.

  • 5.6–9.5× fewer tokens to resume after three files change: a ~102-token diff + two faults (469 / 436 tokens) versus re-reading the changed files (2,607 / 4,127 tokens).

  • Counterfactual on real logs: 7.8× fewer prompt tokens, −56% cost for a last-8-tool-results retention policy (docs/evidence.md).

Every one of the 14 paged runs has 100% coverage of the curated ground-truth file set; C* includes the cost of paging every file the cheap plan missed. The per-task ratio ranges from 1.17× (a tiny single-file fixture task, where plain reads are already cheap) to 5.50× (a locate task on the real 288-file corpus).

Method note. Token counts come from the shipped code over the real corpora, with tokens = ceil(chars / 3.966) calibrated against provider-reported usage (tools/calibrate-session.mjs). Prices are deepseek-flash off-peak list ($0.15 / $0.003 / $0.60 per 1M miss / hit / output tokens); at peak (2×) every dollar figure doubles, while all token ratios are price-independent. This is a controlled benchmark, not a production A/B.

How it works

                    ┌──────────────────────────────────────────────┐
  Claude Code       │  MCP server (memai-mcp)   CLI (memai)         │
  Codex             │  one `mem` tool, 11 ops    same surface       │
  OpenCode     ───► │  JSON-RPC over stdio       JSON on stdout     │
  ZCode             └──────────────────┬───────────────────────────┘
  DSH plugin                           │ page ids · symbol anchors · version hashes
                    ┌──────────────────▼───────────────────────────┐
                    │  pages: project.card · project.map · file:*  │
                    │         board:* · Merkle versions · deltas   │
                    └──────────────────┬───────────────────────────┘
                                       │ deterministic extraction (0 model tokens)
                    ┌──────────────────▼───────────────────────────┐
                    │  git ls-files · symbol/import regexes ·      │
                    │  build files · tests · FTS5 symbol index     │
                    └──────────────────┬───────────────────────────┘
                                       ▼
                    .memai/mem.db  (SQLite, WAL, one writer, many readers)

Session loop: card once → query → fault the one symbol the task needs → edit → index (local, cheap) → next session diff --since <hash> → fault only what the delta names. Subagents get the same card plus the parent's version hash instead of a prose summary. Other agents read the board, not a steering queue.

The rule that makes it pay: never inline what can be referenced; keep the shared prefix byte-identical so the provider's prefix cache can hit; page in hundreds of tokens, not thousands.

Quick start

npm publish is pending. Until memai-cli is on npm, install straight from this repo — npm i -g github:ZrifBSofiane/MemAi — or clone it and run node bin/memai.mjs …. The npx commands below are the intended published form (the memai-cli name was free on npm at release time).

# 1. Create the store, index the repo, install the Agent Skills package,
#    write per-agent instructions and MCP snippets
npx -y memai-cli init --agent all

# 2. Distil the repo locally (0 model tokens, no network)
npx -y memai-cli index

# 3. Use it
npx -y memai-cli card                  # ~200-token orientation, once per session
npx -y memai-cli query "where is auth checked"
npx -y memai-cli fault verifyToken     # one body slice, budget-clamped
npx -y memai-cli diff --since <version>  # on the next session / in a subagent

Or install once — there is nothing to compile and no runtime dependency:

npm i -g memai-cli
memai init --agent all

init writes an idempotent instruction block between <!-- memai:start --> / <!-- memai:end --> markers into CLAUDE.md and/or AGENTS.md, drops ready-to-paste MCP config snippets under .memai/configs/, and (with --write-configs) safely merges project-scope MCP entries. It never touches source files, and a second run changes nothing. --md previews the instruction block without writing.

MCP clients start the server directly:

npx -y -p memai-cli memai-mcp --root .   # stdio JSON-RPC; logs on stderr only
node bin/memai-mcp.mjs --root .          # from a checkout

The store lives in .memai/mem.db under the project root. Override the root or the store file with --root / --db, or with MEMAI_ROOT / MEMAI_DB.

Connect your agent

memai init --agent all generates config snippets for all of these. Exact keys, verification steps and the no-MCP CLI fallback are in docs/install.md; the per-agent evidence (what was verified on an install vs copied from vendor docs) is in docs/compatibility.md and in each adapter README.

Agent

Instructions

MCP

Auto-inject

Adapter

Claude Code

CLAUDE.md block

project .mcp.json → mcpServers.memai, or claude mcp add

SessionStart/SubagentStart hooks (memai hook card) + skill

adapters/claude-code/

Codex

AGENTS.md block

~/.codex/config.toml → [mcp_servers.memai]

instruction block only

adapters/codex/

OpenCode

AGENTS.md block

opencode.json → mcp.servers.memai (v2 shape)

initialize.instructions appended by OpenCode

adapters/opencode/

ZCode

AGENTS.md block

~/.zcode/cli/config.json → mcp.servers.memai

process hook on SessionStart (opt-in)

adapters/zcode/

DeepSeek Harness (DSH)

in-process plugin guidance + AGENTS.md

MCP server (supported path)

experimental in-process bundle

adapters/dsh/

Generic MCP (Cursor, Zed, Cline, Gemini CLI, …)

the agent's rules file

mcpServers JSON (Zed: context_servers)

—

adapters/generic/

MemAi never invents vendor config keys: each adapter states what it verified on a real install (and the version), what comes from vendor documentation, and what is unknown. The evidence matrix is docs/compatibility.md.

Skills — one file, every agent

skills/memai/SKILL.md is a portable Agent Skills package. It teaches an agent when MemAi is worth using versus a plain file read — card → query → fault → diff, the mem MCP tool and the memai CLI fallback, the measured ~346-token / ~1.3 KB break-even, and the common pitfalls — and uses standard frontmatter only (name, description, license, compatibility, metadata), so strict clients accept it unchanged.

memai init installs it by default into the two roots agents actually scan:

Install path

Agents that scan it

.agents/skills/memai/SKILL.md

Codex, OpenCode, ZCode, DSH, Cursor, Gemini CLI, generic SKILL.md hosts

.claude/skills/memai/SKILL.md

Claude Code (its only project skill root — verified); OpenCode and Cursor also read it

memai skill install                         # project scope, all agents (default)
memai skill install --agent claude          # one agent alias
memai skill install --global                # ~/.agents/skills + ~/.claude/skills
memai skill install --link --force          # symlink/junction; replace a differing target
memai skill list                            # installed / missing / differs
memai skill status                          # same, with a summary

The installer is content-hash idempotent (re-runs report unchanged, no timestamp churn), keeps both copies byte-identical to the repo source, and never overwrites a different memai skill directory without --force. Verify with memai skill list and the agent's own skill catalog (Claude Code: /skills, then /memai). Per-agent roots and optional fallbacks: docs/install.md#agent-skills-one-skill-every-agent.

Verified here vs documented only

Verified on this machine (Windows 11, Node 24.14, SQLite 3.53):

  • the store, extractor, pager, budget clamping, delta and board: 18/18 node bench/selftest.mjs checks pass;

  • the benchmark numbers above (node bench/bench.mjs, rerun);

  • the MCP stdio handshake, tool list (one mem tool by default, 11 granular tools under MEMAI_GRANULAR_TOOLS=1), tools/call, resources and the clean-stdout invariant (node --test "test/*.test.mjs", node scripts/mcp-probe.mjs);

  • memai init idempotency, instruction markers, hook payload shape and safe .mcp.json merging (node --test "test/*.test.mjs");

  • the DSH plugin against a fake host (node adapters/dsh/test/apply.test.mjs);

  • Claude Code 2.1.140: project .mcp.json registration + health check, claude mcp add -s project|user, ${CLAUDE_PROJECT_DIR:-.} expansion, and project settings hooks being loaded/fired by the CLI (no model calls made);

  • OpenCode v2.2.5: the mcp.servers config shape, opencode mcp add, and the opencode mcp list health check showing ✓ memai connected (a v1-era mcp.memai entry is ignored by v2);

  • the memai skill installer: byte-identical copies in .agents/skills and .claude/skills, content-hash idempotency, --force/--link/--global behavior and the init integration (node --test "test/*.test.mjs", 12 skill tests), plus Claude Code 2.1.140 skill discovery (Loaded N unique skills (… project: 1 …) after memai skill install).

Documented only (not installed on the build machine, so not executed): the Codex config shape, the ZCode mcp.servers/process-hook shapes (taken from the ZCode CLI source and README), the rendering of the injected card inside a live model session, and the generic-MCP client entries (Cursor/Zed/Cline/Gemini, with per-client links in adapters/generic/). Each adapter README says which is which; if a vendor changes its schema, the adapter is the place to fix it — no core code.

Not claimed: a production A/B. The benchmark and the replay are controlled measurements; the next experiment is a real with/without trial (success bar: ≥5× fewer total tokens, ≥90% cache-hit share on the shared prefix, no accuracy regression).

Limitations

MemAi is honest about where paging loses. All of these are measured, not guessed:

  • Small tasks lose. If the task needs one file under ~1.2 KB (~300 tokens) or one symbol, plain read is cheaper. Measured break-even: ≤ ~346 tokens (~1.3 KB) of file bodies. Paging pays when the target is >~2 KB, when ≥2 files are involved, or for a second question in the same session.

  • Query overhead is real. A tool call costs ~45 tokens before content; many tiny queries lose to one full read. Use fewer, larger faults; stop when the question is answered.

  • The index can be stale. Re-index after checkouts/edits (local, tens to hundreds of ms). fault reads the file from disk but line numbers come from the index — use fault <path>:<line> if exactness matters.

  • Extraction is regex-based. One-line or dynamic constructs can be missed; fault <path>:<line> and raw read are the fallbacks.

  • Single store, single writer. The board coordinates agents on one machine sharing one .memai/mem.db. Cross-machine sharing needs a shared path or a sync layer (not in v1).

  • Out-of-process agents don't inherit host context. A DSH in-process plugin can inject the card into every in-process child; Claude Code / Codex / OpenCode / ZCode reach MemAi through MCP or the CLI, and inject the card via their own instruction/hook mechanism.

  • The DSH plugin is experimental. adapters/dsh/ is an in-process bundle that keeps its own board store (under $DSH_HOME) and reads pages produced by the indexer; it is tested against a fake host, not installed in a live profile. The supported way to use MemAi from DSH is the MCP server or the CLI.

  • Node.js ≥ 22.13. The store uses the built-in node:sqlite (still marked experimental by Node; its warning is filtered so stdout stays clean JSON). There are no native modules.

  • No embeddings. Structure first; semantic reranking is a possible future option for prose notes, not the core.

Repository layout

src/          store (SQLite/WAL/FTS5), extractor, pager, token estimator, core CLI, skill installer
mcp/          stdio MCP server, tool definitions, resources, SessionStart hook
bin/          memai, memai-mcp executables (root resolution, init, skill, hook, mcp)
skills/       portable Agent Skills package (skills/memai/SKILL.md), installed by init / memai skill
adapters/     claude-code · codex · opencode · zcode · generic · dsh
bench/        fixture generator, corpora/tasks, benchmark, selftest, RESULTS.md
test/         unit + MCP protocol + init/hook/skill tests (node --test)
scripts/      mcp-probe.mjs (live handshake probe for CI/humans)
examples/     minimal copy-ready configs
tools/        token-estimator calibration against real session logs
docs/         install · compatibility · protocol · design · evidence · faq
PROTOCOL.md   normative page/version/delta/tool contract for implementers

Docs

Development

node bench/selftest.mjs           # 18/18 end-to-end checks
node --test "test/*.test.mjs"     # unit + MCP protocol + init/hook/skill tests
node --check mcp/server.mjs       # syntax
node scripts/mcp-probe.mjs        # live JSON-RPC handshake + tool list
node bench/bench.mjs              # regenerate bench/RESULTS.md

There is nothing to install: zero dependencies, plain ESM .mjs. CI runs the suite on Node 22 and 24 with no install step. See CONTRIBUTING.md for the adapter-adding guide and the documentation rules.

License & security

MIT — see LICENSE. MemAi is local-only and has no dependencies; it never sends your code anywhere. Read SECURITY.md before indexing repositories that contain secrets.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      Enables Claude Code agents and sub-agents to share a persistent, compiled memory of project state, decisions, tasks, and facts across sessions instead of re-reading transcripts. Provides token-efficient bootstrap, search, commit, leased task claiming, and task-specific context compilation so parallel agents can coordinate without clobbering each other.
      5
      20 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to keep project state, evidence, and decisions bound to the repository, and to resume work across sessions and hosts by receiving a bounded, revalidated context packet instead of a full transcript. It also lets agents record checkpoints, handoffs, and closeouts while keeping deterministic decision and routing authority in code.
      2
      Apache 2.0