memai-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.
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 |
|
One manifest |
|
Demand paging |
|
Merkle deltas |
|
A shared board |
|
One integration surface | A stdio MCP server ( |
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-cliis on npm, install straight from this repo —npm i -g github:ZrifBSofiane/MemAi— or clone it and runnode bin/memai.mjs …. Thenpxcommands below are the intended published form (thememai-cliname 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 subagentOr install once — there is nothing to compile and no runtime dependency:
npm i -g memai-cli
memai init --agent allinit 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 checkoutThe 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 |
| project |
| |
Codex |
|
| instruction block only | |
OpenCode |
|
|
| |
ZCode |
|
| process hook on | |
DeepSeek Harness (DSH) | in-process plugin guidance + | MCP server (supported path) | experimental in-process bundle | |
Generic MCP (Cursor, Zed, Cline, Gemini CLI, …) | the agent's rules file |
| — |
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 |
| Codex, OpenCode, ZCode, DSH, Cursor, Gemini CLI, generic SKILL.md hosts |
| 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 summaryThe 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.mjschecks pass;the benchmark numbers above (
node bench/bench.mjs, rerun);the MCP stdio handshake, tool list (one
memtool by default, 11 granular tools underMEMAI_GRANULAR_TOOLS=1),tools/call, resources and the clean-stdout invariant (node --test "test/*.test.mjs",node scripts/mcp-probe.mjs);memai initidempotency, instruction markers, hook payload shape and safe.mcp.jsonmerging (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.jsonregistration + 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.serversconfig shape,opencode mcp add, and theopencode mcp listhealth check showing✓ memai connected(a v1-eramcp.memaientry is ignored by v2);the
memai skillinstaller: byte-identical copies in.agents/skillsand.claude/skills, content-hash idempotency,--force/--link/--globalbehavior 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 …)aftermemai 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
readis 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).
faultreads the file from disk but line numbers come from the index — usefault <path>:<line>if exactness matters.Extraction is regex-based. One-line or dynamic constructs can be missed;
fault <path>:<line>and rawreadare 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 implementersDocs
Protocol v1 · normative PROTOCOL.md
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.mdThere 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
Shared memory for coding agents. Stop re-explaining your codebase every session.
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
Project memory, documentation and controlled secret access for AI coding agents.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables coding agents to incrementally index project text and code, persist decisions and constraints with clear sources, and assemble focused project context across sessions via MCP.3433 npm10MIT
- AlicenseNot gradedqualityCmaintenanceProvides AI coding agents with fast, deterministic access to code graphs, knowledge lifecycle state, and cross-document symbol links, enabling compact context retrieval and seamless session handoffs.1MIT
- AlicenseCqualityBmaintenanceEnables 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.520 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables 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.2Apache 2.0