memX: a local memory layer for Codex, Claude Code and OpenClaw agents

The problem memX addresses: finished agent work that nothing remembers

Coding agents are good at acting inside a session and bad at carrying anything out of it. The transcript is the memory. When the session ends, the reasoning that produced a fix, the constraint a reviewer imposed, the shape of a config that failed, all of it goes with it. The next session starts from zero and re-derives what the last one already knew.

memX targets that gap. The README describes the goal as turning completed work into structured, searchable, self-maintained memory, then injecting only the evidence an agent needs for the current query. Two words carry the weight. Structured means memory is not a raw transcript dump but something compiled. Self-maintained means the store is expected to prune or revise itself rather than grow monotonically, which is the failure mode of every append-only note file an agent writes.

The audience is specific. This is for people who already run Codex, Claude Code or OpenClaw as a daily driver and who feel the missing-context tax. It is not a general vector database and not a RAG framework. The README frames it as a plugin with native lifecycle hooks, which tells you it is meant to sit inside an existing agent loop rather than be called by your own code.

How memX works: compile at turn end, recall at query time

The README names three LLM-backed stages: memory compilation, recall planning, and maintenance. Compilation turns completed work into structured records. Recall planning decides what to fetch for the current query. Maintenance keeps the store from degrading. All three run through the same provider adapter you configure, which is why the README advises picking a fast, low-cost model with reliable JSON output. The JSON requirement is not decoration: if a stage cannot parse the model's output, the pipeline has nothing to write.

Retrieval is hybrid in the sense the topics list implies. The repository tags include embeddings and graph-memory, and the default embedding runtime is local sentence-transformers-local with intfloat/multilingual-e5-small. So there are at least two retrieval signals: vector similarity from the local embedding model, and whatever structure the graph layer contributes. The README does not spell out the fusion, and I cannot confirm the ranking logic from the material provided.

The data flow at runtime is a loop. A turn completes, a hook fires, compilation runs, records are written to a local database. A new query arrives, recall planning runs, selected evidence is injected into the agent's context. The README's phrase is that only the evidence an agent needs is injected, which is the design intent: a bounded injection rather than a context dump.

Everything lives locally. The managed service runs on http://127.0.0.1:3878 by default, and the store is a local database. Your prompts and compiled memories do leave the machine to reach the LLM provider you configured, since compilation and recall planning are model calls. That is worth stating plainly, because local storage is not the same as local processing.

Install paths for Codex, Claude Code, OpenClaw and generic MCP clients

One command per host. For Claude Code:

npx -y -p github:NeoLi00/memX memx quickstart claude-code --llm-provider openai-compatible --llm-base-url https://llm.example.com/v1 --llm-model fast-memory-model --llm-api-key sk-your-provider-key

Codex and OpenClaw follow the same shape with quickstart codex and quickstart openclaw. Generic MCP clients use quickstart mcp, which writes the shared config, starts the service, and prints a copy-ready MCP server config instead of installing hooks.

Four flags carry the configuration. --llm-provider takes one of openai-compatible, anthropic, google or ollama. --llm-base-url takes the endpoint, with the README listing https://api.openai.com/v1, https://api.anthropic.com/v1, https://generativelanguage.googleapis.com/v1beta and http://127.0.0.1:11434 for Ollama. --llm-model names the model used across all three stages. --llm-api-key supplies the credential, and --llm-api-key-env PROVIDER_API_KEY is the alternative that stores a reference to an environment variable instead of plaintext. For local Ollama the key is omitted entirely.

Embeddings are configured separately and default to the local runtime, so you only pass --embedding-provider and --embedding-model to override. Requirements are Node.js 22.14+ or Node 24, Python 3 for the default local embedding runtime, and OpenClaw 2026.3.25+ for that host. Add --dry-run to preview files and exec-form commands before anything is written.

Service control is three subcommands: memx service status, memx service restart, memx service stop. If you installed with a non-default --home, --memx-url or --memx-secret, you must pass the same values to service commands or you will be talking to the wrong instance.

The MCP tool surface is deliberately hidden, and that is a real design decision

Quickstart for Codex and Claude Code installs native lifecycle hooks and passes --mcp-tools none by default. The README gives two reasons. First, exposing both hooks and MCP tools would let the agent recall and write twice, producing duplicates. Second, the agent could read audit data as a side channel, treating internal memory records as ordinary tool output.

This is a sharper choice than it looks. Most memory plugins expose their full tool surface and let the model decide when to call it. memX inverts that: the lifecycle hooks drive memory automatically, and the model is kept out of the loop unless you opt in with --mcp-tools full. The cost is that you lose model-initiated memory queries. If your workflow depends on the agent deciding mid-task to go look something up, the default configuration will not give you that. Generic MCP quickstart defaults to full precisely because it has no hooks to drive anything.

A second scoping decision matters just as much. Native memories are host-scoped by default, so Codex and Claude Code do not share a database unless you deliberately override the database path and actor settings. That is a defensible default: two agents with different prompting conventions writing into one store can pollute each other's recall. It also means the cross-agent memory that sounds appealing in the abstract requires explicit configuration, not a flag flip.

Where memX is the wrong tool, and what the README leaves open

The install path is the first constraint. The README commands use the GitHub package spec github:NeoLi00/memX, and it states plainly that a fresh run pulls current GitHub code so installs do not wait for an npm publish. The npm channel exists as @neoli00/memx, but the README frames it as something to switch to later. If your environment requires a pinned, published version, or if your CI blocks installs from a git spec, the documented path does not fit. There are no retrieved releases either, so there is no version number to pin against.

A model endpoint is not optional. Compilation, recall planning and maintenance all run through the configured provider. Air-gapped setups or teams that cannot send code context to an external API need the ollama route, and the README does not discuss what quality difference that introduces.

The port is a hard stop, not a warning. If http://127.0.0.1:3878 is already held by an unmanaged memX-compatible service, quickstart stops rather than silently reusing it. The README's remedy is to stop the old service or pass a free URL such as --memx-url http://127.0.0.1:3888. Sharing a port with another memory tool will not work.

The benchmark table needs reading carefully. It reports R@3 success rate: 94.2% on LongMemEval-S for long-context memory retrieval, and 100% on 30 real engineering cases with 20+ turns each. R@3 measures whether a correct item appears in the top three results, which is a retrieval metric, not a measure of whether the injected memory improved the agent's answer. Thirty cases is a small sample, and the README gives no methodology. The architecture document is linked as ARCHITECTURE.md, and that is where the retrieval and maintenance mechanics would need to be verified.

Compared with a plain vector store plus hand-written notes

The obvious alternative is the one most teams already have: an embeddings table you query yourself, plus a CLAUDE.md or AGENTS.md file that a human curates. The difference in approach is where the work happens.

A vector store gives you retrieval and nothing else. Chunking, deciding what is worth storing, and deciding what to delete are your problems. The curated markdown file solves the opposite problem: high precision, manually maintained, and it stops scaling the moment the project has more than a few dozen facts worth remembering. Neither compiles a finished turn into a record, and neither maintains itself.

memX sits between them. It owns the write path (hooks capture completed turns), the compile step (an LLM turns them into structured records), and the maintenance step. The trade is control for automation. With a hand-rolled store you choose the schema and the chunking strategy. With memX you get the pipeline the README describes, and the schema is whatever its compilation stage produces. If you need to query memory records from your own tooling, the README does not document a query interface beyond the MCP tool set, so plan on reading the database directly.

The honest comparison is effort. Building a compile-and-recall pipeline over an existing vector store is a project. Installing memX is one command with four flags. That is the actual pitch, and it is a reasonable one.

Maintenance, uninstall and licence terms

The uninstall path is unusually well specified, which is a good sign for a tool that writes hooks and config. Each uninstall command backs up the target config first, then removes only memX-owned entries. Claude Code and Codex cleanup also stop the managed service, uninstall the native plugin, remove the local marketplace, and delete the generated marketplace snapshot. OpenClaw cleanup additionally removes stale memx and memory-memx slot, allow and entry references, then attempts to uninstall both current and legacy plugin files if OpenClaw can still see them. Add --dry-run to preview, or --config to point at a specific config file.

Upgrade cost is tied to the GitHub spec. Because a fresh npx run pulls current code, you are tracking main. There is no retrieved release history and no version pinning in the documented commands, so an upgrade is whatever the next pull contains. If you need reproducibility, the npm channel at @neoli00/memx is the lever the README mentions, though it does not say how the two channels stay in sync.

Runtime cost has two parts. The local service must be running for hooks to fire, so memx service status belongs in whatever you already use to check background processes. The model calls are the variable cost: every compiled turn and every recall plan is a request to your provider, which is why the README recommends a fast, low-cost model. With Ollama the marginal cost is local compute instead.

Licence is MIT. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. It also means no warranty and no liability from the authors. This is a description of the licence text, not legal advice; if memX ends up inside a product you ship, have your own counsel review how you distribute it and what notices you bundle.

Editorial conclusion

Adopt memX if you run Codex, Claude Code or OpenClaw daily and want session history compiled into a queryable local store without building the pipeline yourself. Skip it if you need a published npm release, cannot point it at an LLM endpoint, or expect two different coding agents to read one shared memory. Before installing, verify three things: that Node.js 22.14+ and Python 3 are present, that port 3878 is free or you have chosen another --memx-url, and that your provider accepts the model named in --llm-model. Then run the quickstart with --dry-run first and read the exec-form commands it prints, because that preview is the only description of what lands on disk before it lands.

Official sources

1. Issues
2. License: MIT
3. NeoLi00/memX on GitHub
4. README