<div align="center">

🧠 memgw

Shared long-term memory for AI coding agents.

One store that Claude Code, Codex CLI, opencode, and anything that speaks MCP can all read from and write to. Your agents stop forgetting you every session.

English · Tiếng Việt

npm install -g @holetex/memgw && memgw setup

</div>

One command: it creates ~/.memgw, generates keys, asks for your LLM key, wires up Claude Code (hooks + MCP) and Codex (MCP) when they are on the machine, starts the gateway, and ends with a health check. What it does NOT fully automate, it says out loud: reboot supervision is installed automatically on macOS (launchd) and Linux (systemd --user) from a permanent checkout (npm i -g @holetex/memgw or a clone), while Windows / npx-cache runs get the exact Task Scheduler / install command printed instead; opencode gets a one-line copy command. When Codex CLI is found, its transcript watcher (Codex has no hooks) is installed supervised too on macOS/Linux — elsewhere the exact memgw watch --agent codex command is printed.

Just want to try it without installing anything? npx @holetex/memgw setup works too — same wizard, but running from the npx cache means no reboot supervision (the wizard says so and prints the permanent-install command). Prefer doing everything by hand? memgw start just starts the gateway and prints the commands.

Prefer delegating? Tell your agent: "install memgw — follow https://github.com/holetexvn/memgw/blob/main/AGENTS.md". AGENTS.md is a playbook written for agents: non-interactive setup, what to ask you (the LLM key), and how to verify the install.

---

The problem

Every agent keeps its memory in its own silo. Claude Code on your laptop knows nothing about the session you ran on your desktop. Codex knows nothing about either. Close the terminal and the context is gone.

The expensive part of your day is not writing code, it is re-explaining context: what this project is, which conventions apply, what not to touch, and what you already tried last week that did not work.

memgw keeps that in one place. Every agent writes to it, every agent reads from it.

Architecture

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/architecture-en-dark.svg"> <img alt="memgw architecture: agents, gateway, store" src="docs/assets/architecture-en-light.svg"> </picture>

Three layers, each more distilled than the last:

Layer	What	Written by	Lifetime
events	raw conversation turns	capture, no LLM involved	90 days
facts	one-sentence atoms, deduplicated	worker, 2 LLM calls per batch	forever
notes	Markdown topic files in a git repo	worker, agentic loop	forever

Capture is cheap and dumb on purpose: it writes raw turns and returns immediately, so it never slows an agent down. Everything expensive happens later, in the background.

A session with memgw

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/session-en-dark.svg"> <img alt="a session with memgw" src="docs/assets/session-en-light.svg"> </picture>

Retrieval follows one rule that matters: stable context is injected once at session start (profile, topic index) so it stays inside the prompt cache, while specific facts are exposed as tools for the agent to call when it actually needs them. Injecting search results on every turn breaks caching and floods the context with noise.

One fact type earns its keep more than the rest: deadend, meaning something you tried that failed and why. Agents love repeating the same mistake; this is what stops them.

Why not just… ?

	Chat history	RAG over transcripts	memgw
Survives closing the terminal	❌	✅	✅
Shared across different agents	❌	❌ per-tool	✅ one store
Distilled (facts, not walls of text)	❌	❌ raw chunks	✅ one-sentence atoms
Remembers what failed and why	❌	⚠️ buried	✅ deadend type
Prompt-cache friendly	❌	❌ injects every turn	✅ inject once + tools
Human-auditable	❌	❌ opaque index	✅ git log -p on notes
Infrastructure needed	—	vector DB + pipeline	one SQLite file

Features

• 🔌 Every MCP agent — Claude Code, Codex CLI, opencode, claude.ai, Hermes, or any CLI via the generic transcript watcher. Five MCP tools, one endpoint.
• 🏠 Local-first — one process, one SQLite file, binds 127.0.0.1. Deploy to a VPS with one installer when you want several machines sharing memory.
• 🔍 Hybrid search — FTS5/BM25 always works (no API, no cost); memgw embed on adds semantic vectors in the same SQLite file, RRF-fused, falling back to BM25 if the embeddings API is down.
• 🪦 Dead-end memory — type=deadend facts stop agents from retrying what already failed. The most valuable fact type, and the easiest for humans to forget to pass on.
• 📓 Git-audited notes — everything the model writes to Markdown is one git log -p away from inspection and one git revert away from undo.
• 🛡️ Auth is never optional — the server refuses to start without a key, and refuses weak keys off-loopback. There is no configuration in which memgw is an open store.
• 💸 $1–3 / month — cost tracks how much you talk to agents, not store size; every background worker runs off a cursor. Works with any OpenAI-compatible endpoint.
• 🌏 English + Vietnamese prompts — facts come out in the language you work in (MEMGW_PROMPT_LANG=vi). Adding a language is copying one block.

Install

Local

npx @holetex/memgw start              # zero config, binds 127.0.0.1

No LLM key yet? That is the default path, not a degraded one: capture keeps working, events queue locally, and when you add a key later the backlog gets distilled — nothing is lost. Add it whenever you are ready:

memgw key            # masked prompt; provider auto-detected from the key

OpenAI, Anthropic, Groq, and OpenRouter keys are recognised by their prefix and configure the endpoint and a sensible cheap model automatically. Any other OpenAI-compatible endpoint (DeepSeek, local Ollama or vLLM) works too — set MEMGW_LLM_BASE_URL in ~/.memgw/env. The key lives in that file on your machine and is sent only to the provider you chose.

No key at all? npx @holetex/memgw start --mock exercises the entire pipeline without one.

Server

For several machines sharing one store, or for web clients that need a public HTTPS URL:

bash scripts/build-installer.sh          # builds memgw-installer.run from this checkout
scp memgw-installer.run user@vps:/tmp/
ssh user@vps "sudo MEMGW_DOMAIN=memgw.example.com MEMGW_LLM_API_KEY=sk-xxx \
  bash /tmp/memgw-installer.run"

The installer handles Node, a dedicated user, systemd, Caddy with TLS, the firewall, and an optional Litestream backup to S3-compatible storage. See docs/02-OPERATIONS.md.

Connect your agents

Agent	Read	Write
Claude Code	MCP + SessionStart hook	Stop hook
Codex CLI	MCP	transcript watcher
opencode	MCP	native plugin
claude.ai / web	MCP connector	the agent calls memory_save
Hermes	prefetch()	sync_turn()
anything else	MCP, if it speaks it	generic watcher

npx @holetex/memgw hooks                        # Claude Code capture + bootstrap
claude mcp add --transport http memgw http://127.0.0.1:8931/mcp \
  --header "Authorization: Bearer $MEMGW_KEY"

codex mcp add memgw --url http://127.0.0.1:8931/mcp/<MEMGW_MCP_SECRET>
npx @holetex/memgw watch --agent codex          # Codex has no hooks, so watch its transcripts

Full details for every client: docs/03-INTEGRATION.md and docs/05-MULTI-AGENT.md.

Adding an unsupported CLI usually needs no code at all:

npx @holetex/memgw watch --agent generic --dir ~/.some-cli/sessions --once --dry-run

MCP tools

Five tools, available to every connected agent:

Tool	Purpose
memory_search	search distilled facts, filterable by type and topic
conversation_search	search raw transcripts across all agents
memory_read_note	read a topic note or the profile
memory_save	save a fact
memory_bootstrap	profile plus the topic index

CLI

memgw start      Start the gateway
memgw init       Create config without starting
memgw status     Store statistics
memgw doctor     Diagnose configuration and connectivity
memgw search     Search facts from the terminal
memgw save       Save a fact from the terminal
memgw forget     Retire facts (dry-run by default)
memgw key        Set the LLM key later (provider auto-detected, gateway restarted)
memgw embed      Toggle semantic search on or off
memgw watch      Follow agent transcripts
memgw hooks      Install Claude Code hooks

Design choices

SQLite plus FTS5, no vector database. Full-text search is the layer that always works: no API dependency, no cost. Semantic search is one command away (memgw embed on) and lives in the same SQLite file — vectors as BLOBs, fused with BM25, falling back to BM25 whenever the embeddings API is down. Off by default.

Notes are Markdown in a git repo. Memory the model writes is memory you must be able to inspect and correct. git log -p shows every change the worker made, and a bad edit is one git revert away.

Auth is never optional. The server refuses to start without a key. Bind to anything other than loopback and it also demands a strong one. There is no configuration in which memgw is an open memory store.

Best-effort by design. Every call has a timeout, every failure is swallowed and logged. A dead memory store must never take your agent down with it.

The reasoning behind each of these, including what was rejected and why, is in docs/01-ARCHITECTURE.md.

Measured recall

End-to-end on LoCoMo (1,986 questions through the real capture → extraction → dedup → search pipeline, LLM-judged):

Retrieval	Overall	Refuses correctly when memory has no answer
BM25 (default)	58.6%	84.5%
+ embeddings (memgw embed on)	66.4%	80.3%

On PersonaMem (COLM 2025, 32k-token tier, 589 multiple-choice questions on user personalization): 59.6% against a 25% random baseline, end-to-end through the same pipeline.

Methodology, per-category numbers, and how to reproduce it for ~$4: docs/06-BENCHMARKS.md.

Cost

Roughly 15 sessions a day across all agents, with a cheap model, comes to about 60 LLM calls and 0.5M tokens per day: $1-3 a month. Cost tracks how much you talk to your agents, not how large the store grows, because every worker runs off a cursor.

Documentation

Document	Read it when
01-ARCHITECTURE	you want to know how it works and why
02-OPERATIONS	deploying, configuring, troubleshooting, backups
03-INTEGRATION	connecting a specific client
04-API	endpoint and MCP tool reference
05-MULTI-AGENT	adding Codex, opencode, or your own CLI
06-BENCHMARKS	measured recall on LoCoMo, and how to rerun it

Prompt language

Extraction prompts ship in English and Vietnamese. The facts a model writes come out in the prompt language, so pick the one you actually work in:

echo 'MEMGW_PROMPT_LANG=vi' >> ~/.memgw/env

Adding a language means copying one block in src/prompts.js. Contributions welcome.

Development

git clone https://github.com/holetexvn/memgw.git
cd memgw && npm install
bash test/run-all.sh          # 11 suites, no API key needed; the runner prints totals

The suite includes verify-docs.mjs, which cross-checks this documentation against the code: endpoints, tool names, and the constants quoted in prose. Change a default without updating the docs and the suite goes red.

See CONTRIBUTING.md.

Prior art

The layered-distillation approach and several implementation details were informed by reading TencentDB Agent Memory (MIT). memgw is a much smaller, single-user take on the same idea: no team management, no ACL layer, no external infrastructure. docs/01-ARCHITECTURE.md has a section comparing the two.

License

MIT

---

<div align="center">

If memgw saves you from re-explaining your project one more time, ⭐ the repo — it helps other people's agents find their memory too.

</div>