Back to search
MegaMemory
MCP serverGitHub
Persistent project knowledge graph for coding agents. MCP server with semantic search, in-process embeddings, and web explorer.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/0xk3vin--megamemory)HTML
<a href="/listings/0xk3vin--megamemory"><img src="/api/listings/0xk3vin--megamemory/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
npm install -g megamemory
> [!NOTE] > Requires Node.js >= 18. The embedding model (~23MB) downloads automatically on first use.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 255 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <p align="center">
- <h1 align="center">MegaMemory</h1>
- </p>
- <p align="center">Persistent project knowledge graph for coding agents.</p>
- <p align="center">
- <a href="https://www.npmjs.com/package/megamemory"><img alt="npm" src="https://img.shields.io/npm/v/megamemory?style=flat-square" /></a>
- <a href="./LICENSE"><img alt="license" src="https://img.shields.io/npm/l/megamemory?style=flat-square" /></a>
- <a href="https://nodejs.org"><img alt="node" src="https://img.shields.io/node/v/megamemory?style=flat-square" /></a>
- <a href="https://www.npmjs.com/package/megamemory"><img alt="npm downloads" src="https://img.shields.io/npm/dm/megamemory?style=flat-square" /></a>
- <a href="https://x.com/M3ruH4sh"><img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/M3ruH4sh?style=social" /></a>
- </p>
- <p align="center">
- <img src="./assets/preview.png" alt="MegaMemory web explorer" width="800" />
- </p>
- ---
- An [MCP](https://modelcontextprotocol.io/) server that lets your coding agent build and query a graph of concepts, architecture, and decisions — so it **remembers across sessions**.
- The LLM is the indexer. No AST parsing. No static analysis. Your agent reads code, writes concepts in its own words, and queries them before future tasks. The graph stores **concepts** — features, modules, patterns, decisions — not code symbols.
- ### The Loop
- <p align="center">
- <img src="./assets/how-it-works.svg" alt="How MegaMemory works" width="800" />
- </p>
- `understand → work → update`
- 1. **Session start** — agent calls `list_roots` to orient itself
- 2. **Before a task** — agent calls `understand` with a natural language query (or `get_concept` for exact ID lookup)
- 3. **After a task** — agent calls `create_concept` or `update_concept` to record what it built
- Everything persists in a per-project SQLite database at `.megamemory/knowledge.db`.
- ---
- ### Installation
- ```bash
- npm install -g megamemory
- ```
- > [!NOTE]
- > Requires Node.js >= 18. The embedding model (~23MB) downloads automatically on first use.
- ### Quick Start
- ```bash
- megamemory install
- ```
- Run the interactive installer and choose your editor:
- > [!NOTE]
- > The installer only updates config files after a successful read/merge, and it will not overwrite existing plugin/command files unless they are already marked as MegaMemory-managed.
- #### With [opencode](https://opencode.ai)
- ```bash
- megamemory install --target opencode
- ```
- One command configures:
- - MCP server in `~/.config/opencode/opencode.json`
- - Workflow instructions in `~/.config/opencode/AGENTS.md`
- - Skill tool plugin at `~/.config/opencode/tool/megamemory.ts`
- - Bootstrap command `/user:bootstrap-memory` for initial graph population
- - Save command `/user:save-memory` to persist session knowledge
- Restart opencode after running install.
- #### With [Claude Code](https://code.claude.com)
- ```bash
- megamemory install --target claudecode
- ```
- Configures:
- - MCP server in `~/.claude.json`
- - Workflow instructions in `~/.claude/CLAUDE.md`
- - Commands in `~/.claude/commands/`
- #### With [Antigravity](https://idx.google.com)
- ```bash
- megamemory install --target antigravity
- ```
- Configures:
- - MCP server in `./mcp_config.json` (workspace-level)
- #### With [Codex](https://openai.com/codex)
- ```bash
- megamemory install --target codex
- ```
- Configures:
- - MCP server in `~/.codex/config.toml`
- - Workflow instructions in `~/.codex/AGENTS.md`
- #### With other MCP clients
- Add megamemory as a stdio MCP server. The command is just `megamemory` (no arguments). It reads/writes `.megamemory/knowledge.db` relative to the working directory, or set `MEGAMEMORY_DB_PATH` to override.
- ```json
- {
- "megamemory": {
- "type": "local",
- "command": ["megamemory"],
- "enabled": true
- }
- }
- ```
- ---
- ### MCP Tools
- | Tool | Description |
- |------|-------------|
- | `understand` | Semantic search over the knowledge graph. Returns matched concepts with children, edges, and parent context. |
- | `get_concept` | Look up a concept by its exact ID. Returns full context including children, edges, incoming edges, and parent. |
- | `create_concept` | Add a new concept with optional edges and file references. |
- | `update_concept` | Update fields on an existing concept. Regenerates embeddings automatically. |
- | `link` | Create a typed relationship between two concepts. |
- | `remove_concept` | Soft-delete a concept with a reason. History preserved. |
- | `list_roots` | List all top-level concepts with direct children. |
- | `list_conflicts` | List unresolved merge conflicts grouped by merge group. |
- | `resolve_conflict` | Resolve a merge conflict by providing verified, correct content based on the current codebase. |
- **Concept kinds:** `feature` · `module` · `pattern` · `config` · `decision` · `component`
- **Relationship types:** `connects_to` · `depends_on` · `implements` · `calls` · `configured_by`
- ### Knowledge Graph
- <p align="center">
- <img src="./assets/knowledge-graph.svg" alt="MegaMemory knowledge graph example" width="800" />
- </p>
- ---
- ### Web Explorer
- Visualize the knowledge graph in your browser:
- ```bash
- megamemory serve
- ```
- - Nodes are colored by kind and sized by edge count
- - Dashed edges show parent-child links; solid edges show relationships
- - Click any node to inspect summary, files, and edges
- - Search supports highlight/dim filtering
- - If port `4321` is taken, you'll be prompted to pick another
- ```bash
- megamemory serve --port 8080 # custom port
- ```
- ---
- ### How It Works
- <p align="center">
- <img src="./assets/architecture.svg" alt="MegaMemory architecture diagram" width="800" />
- </p>
- ```
- src/
- index.ts CLI entry + MCP server (9 tools)
- tools.ts Tool handlers (understand, get_concept, create, update, link, remove, list_conflicts, resolve_conflict)
- db.ts SQLite persistence (libsql, WAL mode, schema v3)
- embeddings.ts In-process embeddings (all-MiniLM-L6-v2, 384 dims)
- merge.ts Two-way merge engine for knowledge.db files
- merge-cli.ts CLI handlers for merge, conflicts, resolve commands
- types.ts TypeScript types
- cli-utils.ts Colored output + interactive prompts
- install.ts multi-target installer (opencode, Claude Code, Antigravity, Codex)
- web.ts HTTP server for graph explorer
- plugin/
- megamemory.ts Opencode skill tool plugin
- commands/
- bootstrap-memory.md /user command for initial population
- save-memory.md /user command to save session knowledge
- web/
- index.html Single-file graph visualization (d3-force + Canvas)
- ```
- - **Embeddings** — In-process via [Xenova/all-MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2) (ONNX, quantized). No API keys, and no network calls after the first model download.
- - **Storage** — SQLite with WAL mode, soft-delete history, and schema migrations (currently v3).
- - **Search** — Brute-force cosine similarity over node embeddings; fast enough for graphs with <10k nodes.
- - **Merge** — Two-way merge with conflict detection by concept ID, with AI-assisted conflict resolution via MCP tools.
- ---
- ### CLI Commands
- | Command | Description |
- |---------|-------------|
- | `megamemory` | Start the MCP stdio server |
- | `megamemory install` | Configure editor/agent integration |
- | `megamemory serve` | Launch the web graph explorer |
- | `megamemory merge` | Merge two knowledge.db files |
- | `megamemory conflicts` | List unresolved merge conflicts |
- | `megamemory resolve` | Resolve a merge conflict |
- | `megamemory --help` | Show help |
- | `megamemory --version` | Show version |
- ---
- ### Merging Knowledge Graphs
- When branches diverge, each may update `.megamemory/knowledge.db` independently. Since SQLite files cannot be auto-merged by git, megamemory provides dedicated merge commands.
- #### Merge two databases
- ```bash
- megamemory merge main.db feature.db --into merged.db
- ```
- Concepts are compared by ID: identical nodes are deduplicated, and conflicting nodes are kept as `::left`/`::right` variants under one merge group UUID. Use `--left-label` and `--right-label` to replace default side labels with branch names.
- ```bash
- megamemory merge main.db feature.db --into merged.db --left-label main --right-label feature-xyz
- ```
- #### View conflicts
- ```bash
- megamemory conflicts # human-readable summary
- megamemory conflicts --json # machine-readable output
- megamemory conflicts --db path # specify database path
- ```
- #### Resolve conflicts manually
- ```bash
- megamemory resolve <merge-group-uuid> --keep left # keep the left version
- megamemory resolve <merge-group-uuid> --keep right # keep the right version
- megamemory resolve <merge-group-uuid> --keep both # keep both as separate concepts
- ```
- #### AI-assisted resolution
- When an AI agent runs `/merge`, it calls `list_conflicts`, verifies both versions against current source files, then calls `resolve_conflict` with `resolved: {summary, why?, file_refs?}` plus a verification `reason`. It does not pick a side blindly; it resolves to what the codebase currently reflects.
- ---
- ### License
- [MIT](./LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.