{"id":43860819,"url":"https://github.com/0xk3vin/megamemory","last_synced_at":"2026-05-03T02:04:40.123Z","repository":{"id":336810371,"uuid":"1151221822","full_name":"0xK3vin/MegaMemory","owner":"0xK3vin","description":"Persistent project knowledge graph for coding agents. MCP server with semantic search, in-process embeddings, and web explorer.","archived":false,"fork":false,"pushed_at":"2026-03-16T01:28:46.000Z","size":566,"stargazers_count":62,"open_issues_count":1,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-16T12:17:39.962Z","etag":null,"topics":["agentic-coding","ai","ai-agents","claude-code","code-context","coding-agent","embeddings","knowledge-graph","llm","mcp","mcp-server","opencode","persistent-memory","sqlite","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xK3vin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T07:40:49.000Z","updated_at":"2026-03-16T01:28:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/0xK3vin/MegaMemory","commit_stats":null,"previous_names":["0xk3vin/megamemory"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/0xK3vin/MegaMemory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xK3vin%2FMegaMemory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xK3vin%2FMegaMemory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xK3vin%2FMegaMemory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xK3vin%2FMegaMemory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xK3vin","download_url":"https://codeload.github.com/0xK3vin/MegaMemory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xK3vin%2FMegaMemory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291348,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","ai","ai-agents","claude-code","code-context","coding-agent","embeddings","knowledge-graph","llm","mcp","mcp-server","opencode","persistent-memory","sqlite","typescript"],"created_at":"2026-02-06T10:14:08.091Z","updated_at":"2026-05-03T02:04:40.114Z","avatar_url":"https://github.com/0xK3vin.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eMegaMemory\u003c/h1\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003ePersistent project knowledge graph for coding agents.\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/megamemory\"\u003e\u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/v/megamemory?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg alt=\"license\" src=\"https://img.shields.io/npm/l/megamemory?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org\"\u003e\u003cimg alt=\"node\" src=\"https://img.shields.io/node/v/megamemory?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/megamemory\"\u003e\u003cimg alt=\"npm downloads\" src=\"https://img.shields.io/npm/dm/megamemory?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://x.com/M3ruH4sh\"\u003e\u003cimg alt=\"Twitter Follow\" src=\"https://img.shields.io/twitter/follow/M3ruH4sh?style=social\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/preview.png\" alt=\"MegaMemory web explorer\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n---\n\nAn [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**.\n\nThe 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.\n\n### The Loop\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/how-it-works.svg\" alt=\"How MegaMemory works\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n`understand → work → update`\n\n1. **Session start** — agent calls `list_roots` to orient itself\n2. **Before a task** — agent calls `understand` with a natural language query (or `get_concept` for exact ID lookup)\n3. **After a task** — agent calls `create_concept` or `update_concept` to record what it built\n\nEverything persists in a per-project SQLite database at `.megamemory/knowledge.db`.\n\n---\n\n### Installation\n\n```bash\nnpm install -g megamemory\n```\n\n\u003e [!NOTE]\n\u003e Requires Node.js \u003e= 18. The embedding model (~23MB) downloads automatically on first use.\n\n### Quick Start\n\n```bash\nmegamemory install\n```\n\nRun the interactive installer and choose your editor:\n\n\u003e [!NOTE]\n\u003e 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.\n\n#### With [opencode](https://opencode.ai)\n\n```bash\nmegamemory install --target opencode\n```\n\nOne command configures:\n- MCP server in `~/.config/opencode/opencode.json`\n- Workflow instructions in `~/.config/opencode/AGENTS.md`\n- Skill tool plugin at `~/.config/opencode/tool/megamemory.ts`\n- Bootstrap command `/user:bootstrap-memory` for initial graph population\n- Save command `/user:save-memory` to persist session knowledge\n\nRestart opencode after running install.\n\n#### With [Claude Code](https://code.claude.com)\n\n```bash\nmegamemory install --target claudecode\n```\n\nConfigures:\n- MCP server in `~/.claude.json`\n- Workflow instructions in `~/.claude/CLAUDE.md`\n- Commands in `~/.claude/commands/`\n\n#### With [Antigravity](https://idx.google.com)\n\n```bash\nmegamemory install --target antigravity\n```\n\nConfigures:\n- MCP server in `./mcp_config.json` (workspace-level)\n\n#### With [Codex](https://openai.com/codex)\n\n```bash\nmegamemory install --target codex\n```\n\nConfigures:\n- MCP server in `~/.codex/config.toml`\n- Workflow instructions in `~/.codex/AGENTS.md`\n\n#### With other MCP clients\n\nAdd 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.\n\n```json\n{\n  \"megamemory\": {\n    \"type\": \"local\",\n    \"command\": [\"megamemory\"],\n    \"enabled\": true\n  }\n}\n```\n\n---\n\n### MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `understand` | Semantic search over the knowledge graph. Returns matched concepts with children, edges, and parent context. |\n| `get_concept` | Look up a concept by its exact ID. Returns full context including children, edges, incoming edges, and parent. |\n| `create_concept` | Add a new concept with optional edges and file references. |\n| `update_concept` | Update fields on an existing concept. Regenerates embeddings automatically. |\n| `link` | Create a typed relationship between two concepts. |\n| `remove_concept` | Soft-delete a concept with a reason. History preserved. |\n| `list_roots` | List all top-level concepts with direct children. |\n| `list_conflicts` | List unresolved merge conflicts grouped by merge group. |\n| `resolve_conflict` | Resolve a merge conflict by providing verified, correct content based on the current codebase. |\n\n**Concept kinds:** `feature` · `module` · `pattern` · `config` · `decision` · `component`\n\n**Relationship types:** `connects_to` · `depends_on` · `implements` · `calls` · `configured_by`\n\n### Knowledge Graph\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/knowledge-graph.svg\" alt=\"MegaMemory knowledge graph example\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n---\n\n### Web Explorer\n\nVisualize the knowledge graph in your browser:\n\n```bash\nmegamemory serve\n```\n\n- Nodes are colored by kind and sized by edge count\n- Dashed edges show parent-child links; solid edges show relationships\n- Click any node to inspect summary, files, and edges\n- Search supports highlight/dim filtering\n- If port `4321` is taken, you'll be prompted to pick another\n\n```bash\nmegamemory serve --port 8080   # custom port\n```\n\n---\n\n### How It Works\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/architecture.svg\" alt=\"MegaMemory architecture diagram\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n```\nsrc/\n  index.ts       CLI entry + MCP server (9 tools)\n  tools.ts       Tool handlers (understand, get_concept, create, update, link, remove, list_conflicts, resolve_conflict)\n  db.ts          SQLite persistence (libsql, WAL mode, schema v3)\n  embeddings.ts  In-process embeddings (all-MiniLM-L6-v2, 384 dims)\n  merge.ts       Two-way merge engine for knowledge.db files\n  merge-cli.ts   CLI handlers for merge, conflicts, resolve commands\n  types.ts       TypeScript types\n  cli-utils.ts   Colored output + interactive prompts\n  install.ts     multi-target installer (opencode, Claude Code, Antigravity, Codex)\n  web.ts         HTTP server for graph explorer\nplugin/\n  megamemory.ts  Opencode skill tool plugin\ncommands/\n  bootstrap-memory.md  /user command for initial population\n  save-memory.md       /user command to save session knowledge\nweb/\n  index.html     Single-file graph visualization (d3-force + Canvas)\n```\n\n- **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.\n- **Storage** — SQLite with WAL mode, soft-delete history, and schema migrations (currently v3).\n- **Search** — Brute-force cosine similarity over node embeddings; fast enough for graphs with \u003c10k nodes.\n- **Merge** — Two-way merge with conflict detection by concept ID, with AI-assisted conflict resolution via MCP tools.\n\n---\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `megamemory` | Start the MCP stdio server |\n| `megamemory install` | Configure editor/agent integration |\n| `megamemory serve` | Launch the web graph explorer |\n| `megamemory merge` | Merge two knowledge.db files |\n| `megamemory conflicts` | List unresolved merge conflicts |\n| `megamemory resolve` | Resolve a merge conflict |\n| `megamemory --help` | Show help |\n| `megamemory --version` | Show version |\n\n---\n\n### Merging Knowledge Graphs\n\nWhen branches diverge, each may update `.megamemory/knowledge.db` independently. Since SQLite files cannot be auto-merged by git, megamemory provides dedicated merge commands.\n\n#### Merge two databases\n\n```bash\nmegamemory merge main.db feature.db --into merged.db\n```\n\nConcepts 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.\n\n```bash\nmegamemory merge main.db feature.db --into merged.db --left-label main --right-label feature-xyz\n```\n\n#### View conflicts\n\n```bash\nmegamemory conflicts            # human-readable summary\nmegamemory conflicts --json     # machine-readable output\nmegamemory conflicts --db path  # specify database path\n```\n\n#### Resolve conflicts manually\n\n```bash\nmegamemory resolve \u003cmerge-group-uuid\u003e --keep left    # keep the left version\nmegamemory resolve \u003cmerge-group-uuid\u003e --keep right   # keep the right version\nmegamemory resolve \u003cmerge-group-uuid\u003e --keep both    # keep both as separate concepts\n```\n\n#### AI-assisted resolution\n\nWhen 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.\n\n---\n\n### License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xk3vin%2Fmegamemory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xk3vin%2Fmegamemory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xk3vin%2Fmegamemory/lists"}