# MegaMemory: a persistent knowledge graph your coding agent writes itself

> MegaMemory is an MCP server that stores concepts, architecture and decisions in a per-project SQLite database so a coding agent can recall them in later sessions. It trades static analysis for LLM-written notes, and that trade shapes both its strengths and its limits.

**0xK3vin/MegaMemory** — Persistent project knowledge graph for coding agents. MCP server with semantic search, in-process embeddings, and web explorer.

- Repository: https://github.com/0xK3vin/MegaMemory
- Stars: 683 · Forks: 71
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/0xk3vin-megamemory

## The problem MegaMemory picks: an agent that forgets between sessions

A coding agent starts each session with no memory of the last one. It re-reads files, re-derives the module layout, and re-learns decisions that were already settled. MegaMemory targets exactly that gap. It is an MCP server, so it plugs into any client that speaks the Model Context Protocol, and it keeps a per-project knowledge graph in a SQLite file at `.megamemory/knowledge.db`. The README frames the audience plainly: developers using coding agents who want those agents to remember across sessions. The unit of storage is a concept, not a code symbol. The README lists six kinds (`feature`, `module`, `pattern`, `config`, `decision`, `component`) and five relationship types (`connects_to`, `depends_on`, `implements`, `calls`, `configured_by`). That vocabulary is deliberately coarse. It is aimed at architecture and intent, the things a symbol index cannot express, and it is why the project says the LLM is the indexer.

## How the understand, work, update loop actually moves data

The README describes a three-step loop. At session start the agent calls `list_roots` to see top-level concepts. Before a task it calls `understand` with a natural language query, or `get_concept` for an exact ID lookup. After the task it calls `create_concept` or `update_concept` to record what changed. Nine tools are exposed in total, including `link`, `remove_concept`, `list_conflicts` and `resolve_conflict`. The retrieval path is worth being precise about. Embeddings are computed in process with `Xenova/all-MiniLM-L6-v2`, a quantized ONNX model producing 384 dimensions. Search is brute-force cosine similarity over the stored node embeddings, which the README itself bounds: fast enough for graphs under 10k nodes. There is no vector index and no ANN structure, so query cost grows linearly with graph size. Persistence is libsql in WAL mode, with soft deletes and a schema currently at v3. The `update_concept` handler regenerates embeddings automatically, so a stale vector after an edit is not a failure mode you have to manage yourself.

## Installing MegaMemory and populating a first graph

The package is published on npm and requires Node.js 18 or newer. The README notes that the embedding model, roughly 23MB, downloads on first use. Install it globally:

```bash
npm install -g megamemory
```

Then run the interactive installer, which asks which editor to configure:

```bash
megamemory install
```

The installer is careful in a way that matters. According to the README, it only updates config files after a successful read and merge, and it will not overwrite plugin or command files unless they are already marked as MegaMemory-managed. For opencode, the non-interactive form is:

```bash
megamemory install --target opencode
```

That single command writes the MCP server entry into `~/.config/opencode/opencode.json`, workflow instructions into `~/.config/opencode/AGENTS.md`, a skill tool plugin at `~/.config/opencode/tool/megamemory.ts`, and two commands: `/user:bootstrap-memory` and `/user:save-memory`. The README says to restart opencode afterwards. Run `/user:bootstrap-memory` to populate the graph for the first time; that is the step that turns an empty database into something `understand` can search. Other targets follow the same shape: `--target claudecode` writes to `~/.claude.json` and `~/.claude/CLAUDE.md`, `--target codex` writes to `~/.codex/config.toml` and `~/.codex/AGENTS.md`, and `--target antigravity` writes a workspace-level `./mcp_config.json`. For any other MCP client, register a stdio server whose command is just `megamemory` with no arguments:

```json
{
  "megamemory": {
    "type": "local",
    "command": ["megamemory"],
    "enabled": true
  }
}
```

The server resolves `.megamemory/knowledge.db` relative to the working directory, and `MEGAMEMORY_DB_PATH` overrides that path. To inspect what the agent wrote, run the bundled explorer, which defaults to port 4321 and prompts for another port if it is taken:

```bash
megamemory serve --port 8080
```

## The index is whatever your model decided to write down

The README is explicit: no AST parsing, no static analysis. The agent reads code and writes concepts in its own words. That is the project's central design bet, and it cuts both ways. On the plus side, the graph can hold things a parser never sees, such as why a module was split or which approach was rejected. On the minus side, the graph is only as good as the model's summarization. If the agent misreads a file, the wrong concept is stored with a confident summary and a 384-dimension embedding, and later sessions retrieve it as if it were verified. Nothing in the described architecture re-derives concepts from source, so there is no automatic check that a stored note still matches the code. The conflict machinery acknowledges this. `list_conflicts` groups unresolved merge conflicts, and `resolve_conflict` asks the caller to supply verified, correct content based on the current codebase. That is a manual repair path, not a guarantee. Treat the graph as a well-organized set of notes, not as ground truth.

## Merging knowledge.db across branches and machines

Because the store is a single SQLite file, two developers working on branches will produce two diverging graphs. MegaMemory ships a two-way merge engine in `src/merge.ts` with conflict detection keyed on concept ID, plus CLI handlers in `merge-cli.ts` and AI-assisted conflict resolution. This is a real feature that most note-taking setups lack, and it is also where the model's limits show. A concept ID identifies a node, so a merge can tell that both sides edited the same concept. It cannot tell that one side renamed a module and the other side added a feature under the old name, because that relationship lives in prose and edges, not in a schema the merger understands. The README does not document how the merge behaves when the two databases were created from different schema versions, and it does not describe a rollback path for a bad merge. Back up `.megamemory/knowledge.db` before merging if the graph represents real work.

## Where MegaMemory is the wrong tool

If you need retrieval that is mechanically derived from the code, this is not it. A symbol index or a language server answers questions about definitions, references and call sites with certainty, and MegaMemory deliberately does not attempt that. If your repositories are small enough that an agent can re-read the relevant files in a single session, the graph adds a maintenance step without adding recall. If your graph would exceed the 10k node range the README cites for brute-force search, the linear scan becomes a latency problem and there is no documented ANN fallback. And if your team does not consistently run the save step after tasks, the graph decays: `update_concept` regenerates embeddings, but nothing regenerates concepts that were never written. The loop depends on the agent actually calling `create_concept` or `update_concept`, which is a behavioural dependency, not a technical one.

## How MegaMemory differs from a code index

The closest comparison is a code indexing or retrieval tool that parses source into symbols and embeds those chunks. Such a tool answers "where is this function called" from the code itself, and its index is refreshed by re-parsing. MegaMemory answers "what did we decide about this area" from notes the agent wrote, and its index is refreshed by the agent deciding to write. The two are complementary rather than competing: a symbol index covers the mechanical layer, MegaMemory covers the intent layer. The practical difference shows up when the code changes. A parser-based index is wrong only until the next parse. A concept store is wrong until someone notices and calls `resolve_conflict` or `update_concept`. That is a higher bar, and it is the reason the project's own vocabulary centers on concepts rather than symbols.

## Maintenance, licence and what the release history shows

MegaMemory is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are retained. That is a permissive baseline, and nothing in the package metadata suggests dual licensing or a separate commercial tier. On maintenance: the repository is not archived, and the last push was on 2026-05-03, the same day as the v1.6.2 release. The release cadence visible in the tags runs v1.6.0 on 2026-03-16, v1.6.1 on 2026-03-20 and v1.6.2 on 2026-05-03, so the project was shipping steadily through that window. That is not the same as a guarantee of ongoing work, and anyone evaluating it for a long-lived codebase should weigh the gap between that last push and their own adoption date. Upgrade cost is modest on the surface: `npm install -g megamemory` replaces the binary, and schema migrations are handled internally at v3. The risk sits in the database. The README does not document a downgrade path for `.megamemory/knowledge.db` once a migration has run, so a version pin plus a file copy is the conservative move before upgrading a graph you care about.

## Conclusion

Adopt MegaMemory if you already run an MCP-capable agent such as opencode or Claude Code on a codebase you return to across many sessions, and you want the agent's own notes to survive restarts. Skip it if your work is one-off scripts or if you need retrieval that is derived from the code rather than written by a model, because nothing in the repository verifies that a stored concept still matches the source. Before trusting it, run megamemory install --target opencode, execute /user:bootstrap-memory on a small repository, and inspect the resulting graph in megamemory serve to judge whether the concepts your agent wrote are the ones you would have written.

## FAQ

### How do I install MegaMemory and connect it to my editor?

Install the npm package globally with npm install -g megamemory, which requires Node.js 18 or newer, then run megamemory install and pick your editor. For opencode specifically, megamemory install --target opencode writes the MCP server entry, workflow instructions and plugin in one step, and the README says to restart the editor afterwards.

### Does MegaMemory parse my source code or use an AST?

No. The README states that the LLM is the indexer, with no AST parsing and no static analysis. The agent reads code and writes concepts in its own words, and the graph stores concepts such as features, modules, patterns and decisions rather than code symbols.

### Where does MegaMemory store its data, and can I move it?

Everything persists in a per-project SQLite database at .megamemory/knowledge.db, resolved relative to the working directory. Setting the MEGAMEMORY_DB_PATH environment variable overrides that location.

### Does MegaMemory need an API key or a network connection?

No API keys are required. Embeddings run in process through Xenova/all-MiniLM-L6-v2, a quantized ONNX model of about 23MB that downloads automatically on first use, and the README says there are no network calls after that first download.

### How large can the knowledge graph get before search slows down?

Search is brute-force cosine similarity over node embeddings, and the README describes it as fast enough for graphs with fewer than 10k nodes. There is no documented approximate-nearest-neighbour index, so query cost scales with the number of nodes.

## Sources

- [0xK3vin/MegaMemory on GitHub](https://github.com/0xK3vin/MegaMemory)
- [Issues](https://github.com/0xK3vin/MegaMemory/issues)
- [License: MIT](https://github.com/0xK3vin/MegaMemory/blob/main/LICENSE)
- [README](https://github.com/0xK3vin/MegaMemory/blob/main/README.md)
- [Releases](https://github.com/0xK3vin/MegaMemory/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/0xk3vin-megamemory