Skip to content
Back to search

MegaMemory

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/0xk3vin--megamemory/badge.svg)](/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)

  1. <p align="center">
  2. <h1 align="center">MegaMemory</h1>
  3. </p>
  4. <p align="center">Persistent project knowledge graph for coding agents.</p>
  5. <p align="center">
  6. <a href="https://www.npmjs.com/package/megamemory"><img alt="npm" src="https://img.shields.io/npm/v/megamemory?style=flat-square" /></a>
  7. <a href="./LICENSE"><img alt="license" src="https://img.shields.io/npm/l/megamemory?style=flat-square" /></a>
  8. <a href="https://nodejs.org"><img alt="node" src="https://img.shields.io/node/v/megamemory?style=flat-square" /></a>
  9. <a href="https://www.npmjs.com/package/megamemory"><img alt="npm downloads" src="https://img.shields.io/npm/dm/megamemory?style=flat-square" /></a>
  10. <a href="https://x.com/M3ruH4sh"><img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/M3ruH4sh?style=social" /></a>
  11. </p>
  12. <p align="center">
  13. <img src="./assets/preview.png" alt="MegaMemory web explorer" width="800" />
  14. </p>
  15. ---
  16. 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**.
  17. 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.
  18. ### The Loop
  19. <p align="center">
  20. <img src="./assets/how-it-works.svg" alt="How MegaMemory works" width="800" />
  21. </p>
  22. `understand → work → update`
  23. 1. **Session start** — agent calls `list_roots` to orient itself
  24. 2. **Before a task** — agent calls `understand` with a natural language query (or `get_concept` for exact ID lookup)
  25. 3. **After a task** — agent calls `create_concept` or `update_concept` to record what it built
  26. Everything persists in a per-project SQLite database at `.megamemory/knowledge.db`.
  27. ---
  28. ### Installation
  29. ```bash
  30. npm install -g megamemory
  31. ```
  32. > [!NOTE]
  33. > Requires Node.js >= 18. The embedding model (~23MB) downloads automatically on first use.
  34. ### Quick Start
  35. ```bash
  36. megamemory install
  37. ```
  38. Run the interactive installer and choose your editor:
  39. > [!NOTE]
  40. > 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.
  41. #### With [opencode](https://opencode.ai)
  42. ```bash
  43. megamemory install --target opencode
  44. ```
  45. One command configures:
  46. - MCP server in `~/.config/opencode/opencode.json`
  47. - Workflow instructions in `~/.config/opencode/AGENTS.md`
  48. - Skill tool plugin at `~/.config/opencode/tool/megamemory.ts`
  49. - Bootstrap command `/user:bootstrap-memory` for initial graph population
  50. - Save command `/user:save-memory` to persist session knowledge
  51. Restart opencode after running install.
  52. #### With [Claude Code](https://code.claude.com)
  53. ```bash
  54. megamemory install --target claudecode
  55. ```
  56. Configures:
  57. - MCP server in `~/.claude.json`
  58. - Workflow instructions in `~/.claude/CLAUDE.md`
  59. - Commands in `~/.claude/commands/`
  60. #### With [Antigravity](https://idx.google.com)
  61. ```bash
  62. megamemory install --target antigravity
  63. ```
  64. Configures:
  65. - MCP server in `./mcp_config.json` (workspace-level)
  66. #### With [Codex](https://openai.com/codex)
  67. ```bash
  68. megamemory install --target codex
  69. ```
  70. Configures:
  71. - MCP server in `~/.codex/config.toml`
  72. - Workflow instructions in `~/.codex/AGENTS.md`
  73. #### With other MCP clients
  74. 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.
  75. ```json
  76. {
  77. "megamemory": {
  78. "type": "local",
  79. "command": ["megamemory"],
  80. "enabled": true
  81. }
  82. }
  83. ```
  84. ---
  85. ### MCP Tools
  86. | Tool | Description |
  87. |------|-------------|
  88. | `understand` | Semantic search over the knowledge graph. Returns matched concepts with children, edges, and parent context. |
  89. | `get_concept` | Look up a concept by its exact ID. Returns full context including children, edges, incoming edges, and parent. |
  90. | `create_concept` | Add a new concept with optional edges and file references. |
  91. | `update_concept` | Update fields on an existing concept. Regenerates embeddings automatically. |
  92. | `link` | Create a typed relationship between two concepts. |
  93. | `remove_concept` | Soft-delete a concept with a reason. History preserved. |
  94. | `list_roots` | List all top-level concepts with direct children. |
  95. | `list_conflicts` | List unresolved merge conflicts grouped by merge group. |
  96. | `resolve_conflict` | Resolve a merge conflict by providing verified, correct content based on the current codebase. |
  97. **Concept kinds:** `feature` · `module` · `pattern` · `config` · `decision` · `component`
  98. **Relationship types:** `connects_to` · `depends_on` · `implements` · `calls` · `configured_by`
  99. ### Knowledge Graph
  100. <p align="center">
  101. <img src="./assets/knowledge-graph.svg" alt="MegaMemory knowledge graph example" width="800" />
  102. </p>
  103. ---
  104. ### Web Explorer
  105. Visualize the knowledge graph in your browser:
  106. ```bash
  107. megamemory serve
  108. ```
  109. - Nodes are colored by kind and sized by edge count
  110. - Dashed edges show parent-child links; solid edges show relationships
  111. - Click any node to inspect summary, files, and edges
  112. - Search supports highlight/dim filtering
  113. - If port `4321` is taken, you'll be prompted to pick another
  114. ```bash
  115. megamemory serve --port 8080 # custom port
  116. ```
  117. ---
  118. ### How It Works
  119. <p align="center">
  120. <img src="./assets/architecture.svg" alt="MegaMemory architecture diagram" width="800" />
  121. </p>
  122. ```
  123. src/
  124. index.ts CLI entry + MCP server (9 tools)
  125. tools.ts Tool handlers (understand, get_concept, create, update, link, remove, list_conflicts, resolve_conflict)
  126. db.ts SQLite persistence (libsql, WAL mode, schema v3)
  127. embeddings.ts In-process embeddings (all-MiniLM-L6-v2, 384 dims)
  128. merge.ts Two-way merge engine for knowledge.db files
  129. merge-cli.ts CLI handlers for merge, conflicts, resolve commands
  130. types.ts TypeScript types
  131. cli-utils.ts Colored output + interactive prompts
  132. install.ts multi-target installer (opencode, Claude Code, Antigravity, Codex)
  133. web.ts HTTP server for graph explorer
  134. plugin/
  135. megamemory.ts Opencode skill tool plugin
  136. commands/
  137. bootstrap-memory.md /user command for initial population
  138. save-memory.md /user command to save session knowledge
  139. web/
  140. index.html Single-file graph visualization (d3-force + Canvas)
  141. ```
  142. - **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.
  143. - **Storage** — SQLite with WAL mode, soft-delete history, and schema migrations (currently v3).
  144. - **Search** — Brute-force cosine similarity over node embeddings; fast enough for graphs with <10k nodes.
  145. - **Merge** — Two-way merge with conflict detection by concept ID, with AI-assisted conflict resolution via MCP tools.
  146. ---
  147. ### CLI Commands
  148. | Command | Description |
  149. |---------|-------------|
  150. | `megamemory` | Start the MCP stdio server |
  151. | `megamemory install` | Configure editor/agent integration |
  152. | `megamemory serve` | Launch the web graph explorer |
  153. | `megamemory merge` | Merge two knowledge.db files |
  154. | `megamemory conflicts` | List unresolved merge conflicts |
  155. | `megamemory resolve` | Resolve a merge conflict |
  156. | `megamemory --help` | Show help |
  157. | `megamemory --version` | Show version |
  158. ---
  159. ### Merging Knowledge Graphs
  160. When branches diverge, each may update `.megamemory/knowledge.db` independently. Since SQLite files cannot be auto-merged by git, megamemory provides dedicated merge commands.
  161. #### Merge two databases
  162. ```bash
  163. megamemory merge main.db feature.db --into merged.db
  164. ```
  165. 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.
  166. ```bash
  167. megamemory merge main.db feature.db --into merged.db --left-label main --right-label feature-xyz
  168. ```
  169. #### View conflicts
  170. ```bash
  171. megamemory conflicts # human-readable summary
  172. megamemory conflicts --json # machine-readable output
  173. megamemory conflicts --db path # specify database path
  174. ```
  175. #### Resolve conflicts manually
  176. ```bash
  177. megamemory resolve <merge-group-uuid> --keep left # keep the left version
  178. megamemory resolve <merge-group-uuid> --keep right # keep the right version
  179. megamemory resolve <merge-group-uuid> --keep both # keep both as separate concepts
  180. ```
  181. #### AI-assisted resolution
  182. 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.
  183. ---
  184. ### License
  185. [MIT](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.