Persistent project knowledge graph for coding agents. MCP server with semantic search, in-process embeddings, and web explorer.
TypeScript agentic-codingaiai-agentsclaude-codecode-contextcoding-agentembeddingsknowledge-graphllmmcpmcp-serveropencodepersistent-memorysqlitetypescript
Redesign README with centered hero, badges, preview image, and cleaner layout
0xk3vin4a1ad0429a11
diff --git a/README.md b/README.mdindex 3da8451..7f7a636 100644--- a/README.md+++ b/README.md@@ -1,112 +1,153 @@-# megamemory+<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>+</p>-[](https://www.npmjs.com/package/megamemory)-[](./LICENSE)-[](https://nodejs.org)+<p align="center">+ <img src="./assets/preview.png" alt="MegaMemory web explorer" width="800" />+</p>-Persistent project knowledge graph for coding agents. An MCP server that lets your agent build and query a graph of concepts, architecture, and decisions — so it remembers across sessions.+----## How it works+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. There's no AST parsing or 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 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: understand → work → update**+### The Loop++```+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 to load relevant context+2. **Before a task** — agent calls `understand` with a natural language query3. **After a task** — agent calls `create_concept` or `update_concept` to record what it builtEverything persists in a per-project SQLite database at `.megamemory/knowledge.db`.-## Install+---++### Installation```bashnpm install -g megamemory```-Requires Node.js >= 18. The embedding model (~23MB) downloads on first use.+> [!NOTE]+> Requires Node.js >= 18. The embedding model (~23MB) downloads automatically on first use.-## Setup+### Quick Start-### With opencode+#### With [opencode](https://github.com/anomalyco/opencode)```bashmegamemory init```-This configures everything in one command:-- Adds the MCP server to `~/.config/opencode/opencode.json`-- Appends workflow instructions to `~/.config/opencode/AGENTS.md`-- Installs a skill tool plugin at `~/.config/opencode/tool/megamemory.ts`-- Installs a `/user:bootstrap-memory` command for initial graph population+One command configures everything:+- 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 populationRestart opencode after running init.-### With other MCP clients+#### With other MCP clientsAdd 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.-## MCP Tools+```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. |-| `create_concept` | Add a new concept (feature, module, pattern, config, decision, component) with optional edges and file references. |-| `update_concept` | Update fields on an existing concept. Automatically regenerates the embedding if name or summary changes. |-| `link` | Create a typed relationship between two concepts (connects_to, depends_on, implements, calls, configured_by). |-| `remove_concept` | Soft-delete a concept with a reason. Preserved in history. |-| `list_roots` | List all top-level concepts with their direct children. Good for session-start orientation. |+| `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. |++**Concept kinds:** `feature` · `module` · `pattern` · `config` · `decision` · `component`-## Web Explorer+**Relationship types:** `connects_to` · `depends_on` · `implements` · `calls` · `configured_by`-Visualize the knowledge graph in a browser:+---++### Web Explorer++Visualize the knowledge graph in your browser:```bash-cd your-project/megamemory serve```-Opens a Cytoscape.js graph at `http://localhost:4321` with:-- Nodes colored by kind (feature, module, pattern, config, decision, component)-- Dashed edges for parent-child, solid edges for relationships-- Click-to-inspect detail panel with summary, files, edges, and children-- Search bar with highlight/dim filtering--Use `--port` to change the port:+- Nodes colored by kind, sized by edge count+- Dashed edges for parent-child, solid for relationships+- Click-to-inspect detail panel with summary, files, and edges+- Search with highlight/dim filtering+- Interactive port selection if default (`4321`) is taken```bash-megamemory serve --port 8080+megamemory serve --port 8080 # custom port```-## Commands+---++### CLI| Command | Description ||---------|-------------|-| `megamemory` | Start the MCP stdio server (invoked by your agent framework) |+| `megamemory` | Start the MCP stdio server || `megamemory init` | Configure opencode integration |-| `megamemory serve` | Start the web graph explorer |+| `megamemory serve` | Launch the web graph explorer || `megamemory --help` | Show help || `megamemory --version` | Show version |-## Architecture+---++### How It Works```src/- index.ts CLI entry point + MCP server registration- tools.ts Tool handlers (understand, createConcept, etc.)- db.ts SQLite via better-sqlite3 (nodes + edges tables)+ index.ts CLI entry + MCP server+ tools.ts Tool handlers (understand, create, update, link, remove)+ db.ts SQLite persistence (better-sqlite3, WAL mode)embeddings.ts In-process embeddings (all-MiniLM-L6-v2, 384 dims)types.ts TypeScript types- init.ts `megamemory init` command- web.ts HTTP server for the graph explorer+ cli-utils.ts Colored output + interactive prompts+ init.ts opencode setup wizard+ web.ts HTTP server for graph explorerplugin/megamemory.ts Opencode skill tool plugincommands/- bootstrap-memory.md Opencode /user command for initial population+ bootstrap-memory.md /user command for initial populationweb/index.html Single-file graph visualization (Cytoscape.js)```-## License+- **Embeddings** — In-process via [Xenova/all-MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2) (ONNX, quantized). No API keys. No network calls after first model download.+- **Storage** — SQLite with WAL mode, soft-delete with history, schema migrations.+- **Search** — Brute-force cosine similarity over all node embeddings. Fast enough for knowledge graphs with <10k nodes.++---++### License-MIT+[MIT](./LICENSE)diff --git a/assets/preview.png b/assets/preview.pngnew file mode 100644index 0000000..4840edaBinary files /dev/null and b/assets/preview.png differ