{"_id":"@cogeor/llmem","name":"@cogeor/llmem","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@cogeor/llmem","displayName":"LLMem - Codebase Graph & Documentation","description":"MCP server extension for generating interactive graph visualizations and documentation for codebases","version":"0.2.0","publisher":"cogeor","author":{"name":"Costa Georgantas","email":"c.georgantas@hotmail.com"},"license":"MIT","homepage":"https://github.com/cogeor/llmem","bugs":{"url":"https://github.com/cogeor/llmem/issues"},"repository":{"type":"git","url":"git+https://github.com/cogeor/llmem.git"},"keywords":["mcp","graph","visualization","dependency","documentation","ai","codebase","import","call-graph","architecture"],"engines":{"vscode":"^1.85.0","node":">=20.0.0"},"categories":["Visualization","Other"],"galleryBanner":{"color":"#1e1e2e","theme":"dark"},"extensionKind":["workspace"],"mcpName":"io.github.cogeor/llmem","activationEvents":["onStartupFinished"],"main":"./dist/claude/index.js","exports":{".":"./dist/claude/index.js"},"bin":{"llmem":"bin/llmem"},"contributes":{"commands":[{"command":"llmem.showStatus","title":"LLMem: Show Status"},{"command":"llmem.openPanel","title":"LLMem: Open Panel"}],"configuration":{"title":"LLMem","properties":{"llmem.artifactRoot":{"type":"string","default":".artifacts","description":"Root folder for artifacts (relative to workspace root)."},"llmem.maxFilesPerFolder":{"type":"number","default":20,"minimum":1,"maximum":500,"description":"Maximum number of files to include per folder when building context."},"llmem.maxFileSizeKB":{"type":"number","default":512,"minimum":1,"maximum":10240,"description":"Maximum file size in KB to include in context."}}}},"publishConfig":{"access":"public"},"scripts":{"compile":"npm run compile:vscode && npm run compile:webview-types","compile:vscode":"tsc -p ./tsconfig.vscode.json","compile:webview-types":"tsc --noEmit -p ./src/webview/ui/tsconfig.json","compile:claude":"tsc -p ./tsconfig.claude.json","compile:all":"npm run compile:vscode && npm run compile:webview-types && npm run compile:claude","watch":"tsc -watch -p ./tsconfig.vscode.json","watch:vscode":"tsc -watch -p ./tsconfig.vscode.json","watch:claude":"tsc -watch -p ./tsconfig.claude.json","lint":"eslint src --ext ts","test":"npm run test:unit && npm run test:arch && npm run test:integration","test:unit":"node scripts/run-tests.cjs tests/unit tests/contracts","test:arch":"node scripts/run-tests.cjs tests/arch","test:integration":"node scripts/run-tests.cjs --test-concurrency=1 tests/integration","verify":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && npm ci && npm run build:all && npm test","prepublishOnly":"npm test","ci:local":"act -j build --container-architecture linux/amd64","prepare":"node scripts/install-hooks.js","build:webview":"npx ts-node src/scripts/build_webview.ts","build":"npm run build:vscode","build:vscode":"npm run compile:vscode && npm run compile:webview-types && npm run build:webview","build:claude":"npx ts-node src/scripts/build_claude.ts","build:all":"npm run compile:all && npm run build:webview","pretest":"npm run compile && npm run build:webview && npm run build:claude","prepackage":"npm run compile:production && npm run build:webview","compile:production":"tsc -p ./tsconfig.production.json","scan":"node ./bin/llmem scan","view":"npx ts-node src/scripts/generate_webview.ts","view:graph":"npx ts-node src/scripts/generate_webview.ts --graph-only","file-info":"npx ts-node src/info/cli.ts","file-info:sig":"npx ts-node src/info/cli.ts --signatures","file-info:semantic":"npx ts-node src/info/cli.ts --semantic","serve":"npm run build:claude && npm run build:webview && node ./bin/llmem serve","serve:dev":"npx ts-node src/claude/cli/main.ts serve","graph":"node ./bin/llmem generate","graph:stats":"node ./bin/llmem stats","package":"vsce package","package:claude":"echo 'Claude package - copy dist/claude/* to deployment location'"},"devDependencies":{"@types/fs-extra":"^11.0.4","@types/jsdom":"^21.1.7","@types/node":"^20.10.0","@types/vscode":"^1.85.0","@types/ws":"^8.18.1","@typescript-eslint/eslint-plugin":"^6.13.0","@typescript-eslint/parser":"^6.13.0","@vscode/vsce":"^3.7.1","esbuild":"^0.27.1","eslint":"^8.54.0","ts-node":"^10.9.2","typescript":"^5.3.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","tree-sitter":"^0.22.4","chokidar":"^5.0.0","dompurify":"^3.2.4","fs-extra":"^11.3.2","jsdom":"^25.0.1","marked":"^17.0.1","vscode-jsonrpc":"^8.2.1","vscode-uri":"^3.1.0","ws":"^8.18.3","zod":"^3.22.4","zod-to-json-schema":"^3.22.4"},"peerDependencies":{"tree-sitter-python":"^0.23.0","tree-sitter-cpp":"^0.22.0","tree-sitter-rust":"^0.23.0","@davisvaughan/tree-sitter-r":"^1.2.0"},"peerDependenciesMeta":{"tree-sitter-python":{"optional":true},"tree-sitter-cpp":{"optional":true},"tree-sitter-rust":{"optional":true},"@davisvaughan/tree-sitter-r":{"optional":true}},"_id":"@cogeor/llmem@0.2.0","gitHead":"25b05e4b90565b6101243710ef41e2c87839680f","types":"./dist/claude/index.d.ts","_nodeVersion":"22.16.0","_npmVersion":"11.4.1","dist":{"integrity":"sha512-irlNO85Q+5Z5mMf7Ud99z62swfIOTIWDyiGDgT4lwpXwbVh6PeLrP76Bp/LVWgUB41euyzsFB+fLLHPBkOVtFw==","shasum":"0b67b8acbcbb1df707a45913c65ce983a96dbfd6","tarball":"https://registry.npmjs.org/@cogeor/llmem/-/llmem-0.2.0.tgz","fileCount":25,"unpackedSize":21344705,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIC82Sz9UytI0e4LAVpF8NvbQNbYBgME0XIy3E8oB/NftAiA2Ay2pEGPddwOT2Wn78UtM8fhc51nyHTU8YG76q/wNmA=="}]},"_npmUser":{"name":"cogeor","email":"c.georgantas@hotmail.com"},"directories":{},"maintainers":[{"name":"cogeor","email":"c.georgantas@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/llmem_0.2.0_1779574369429_0.1661740372493954"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-23T22:12:49.294Z","0.2.0":"2026-05-23T22:12:49.697Z","modified":"2026-05-23T22:12:49.885Z"},"maintainers":[{"name":"cogeor","email":"c.georgantas@hotmail.com"}],"description":"MCP server extension for generating interactive graph visualizations and documentation for codebases","homepage":"https://github.com/cogeor/llmem","keywords":["mcp","graph","visualization","dependency","documentation","ai","codebase","import","call-graph","architecture"],"repository":{"type":"git","url":"git+https://github.com/cogeor/llmem.git"},"author":{"name":"Costa Georgantas","email":"c.georgantas@hotmail.com"},"bugs":{"url":"https://github.com/cogeor/llmem/issues"},"license":"MIT","readme":"# LLMem - Codebase Graph & Documentation Tool\r\n\r\n**LLMem** is an MCP (Model Context Protocol) server that provides **interactive graph visualization** of your codebase's import dependencies and function calls, alongside tools for generating architectural documentation.\r\n\r\nWorks with:\r\n- **Claude Code** — as a CLI plugin with live-reloading webview\r\n- **Antigravity IDE / VS Code** — as an extension with integrated panel\r\n\r\nBy pre-computing dependency graphs and structural summaries, LLMem allows MCP agents to provide rich codebase context **without additional reasoning or searching**. This reduces output tokens and enables broader codebase understanding in a single query.\r\n\r\n![LLMem Plugin Overview](images/graph-preview.png)\r\n\r\n**Note:** This project started December 11th, 2025 and is in the alpha stage. I am a team of one, developing this as a hobby. It will always stay free and open-source. If you find issues or have suggestions, please don't hesitate to contact me. You can find more information on the design of the project, and other topics on my [personal website](https://www.costasnotes.ch) and (soon) [substack](https://substack.com/@costageorgantas).\r\n\r\n## 🚀 Key Features\r\n\r\n- **Dual Platform**: Works as a Claude Code CLI plugin or VS Code/Antigravity extension\r\n- **MCP-Native**: Full Model Context Protocol support for AI-powered codebase analysis\r\n- **Graph Visualization**: Interactive visualization of import dependencies and function calls\r\n- **Code Intelligence**: Structural analysis (imports, exports, function signatures) using Tree-sitter parsers\r\n- **Shadow Filesystem**: Maintains a parallel `.arch/` directory with AI-generated documentation\r\n- **Live Reload**: Graph server watches for changes and auto-updates the visualization\r\n\r\n> [!IMPORTANT]\r\n> **Call graphs are TypeScript/JavaScript only.** Other languages (Python, C++, Rust, R) support import graphs only.\r\n\r\n## 🌐 Supported Languages\r\n\r\nLLMem uses tree-sitter for fast, reliable parsing. TypeScript/JavaScript also uses the compiler API for full call graph support.\r\n\r\n| Language | Extensions | Parser | Import Graph | Call Graph |\r\n|----------|------------|--------|:------------:|:----------:|\r\n| TypeScript | `.ts`, `.tsx` | TS Compiler API | ✅ | ✅ |\r\n| JavaScript | `.js`, `.jsx` | TS Compiler API | ✅ | ✅ |\r\n| Python | `.py` | tree-sitter | ✅ | ❌ |\r\n| C/C++ | `.c`, `.h`, `.cpp`, `.hpp`, `.cc`, `.cxx`, `.hxx` | tree-sitter | ✅ | ❌ |\r\n| Rust | `.rs` | tree-sitter | ✅ | ❌ |\r\n| R | `.R`, `.r` | tree-sitter | ✅ | ❌ |\r\n\r\n**To enable additional languages**, install the corresponding tree-sitter grammar:\r\n\r\n```bash\r\nnpm install tree-sitter-python    # Python support\r\nnpm install tree-sitter-cpp       # C/C++ support\r\nnpm install tree-sitter-rust      # Rust support\r\nnpm install @davisvaughan/tree-sitter-r  # R support\r\n```\r\n\r\n> [!TIP]\r\n> TypeScript/JavaScript works out of the box. Other languages require installing their grammar package.\r\n\r\n## 📦 Installation\r\n\r\nPrerequisites:\r\n- Node.js (v20+)\r\n- Claude Code CLI, Antigravity IDE, or VS Code\r\n\r\n### Option A: Claude Code Plugin\r\n\r\n1. **Clone and build**\r\n   ```bash\r\n   git clone https://github.com/cogeor/llmem.git\r\n   cd llmem\r\n   npm install\r\n   npm run build:claude\r\n   ```\r\n\r\n2. **(Optional) Add language support** — install grammars for languages you need:\r\n   ```bash\r\n   npm install tree-sitter-python tree-sitter-cpp  # etc.\r\n   ```\r\n\r\n3. **Add to Claude Code config** (`~/.config/claude/config.json` or `settings.json`):\r\n   ```json\r\n   {\r\n     \"mcpServers\": {\r\n       \"llmem\": {\r\n         \"command\": \"node\",\r\n         \"args\": [\"/path/to/llmem/dist/claude/index.js\"]\r\n       }\r\n     }\r\n   }\r\n   ```\r\n\r\n4. **Start the graph server** (in your project directory):\r\n   ```bash\r\n   npm run serve\r\n   ```\r\n   This starts a live-reloading webview at `http://localhost:5757` (override with `--port`).\r\n\r\n> [!NOTE]\r\n> `dist/claude/index.js` (the MCP server) and `npm run serve` (the graph server) are **two separate processes**. The MCP server handles tool calls from Claude; the graph server serves the visualization UI. Both must be running for the full experience.\r\n\r\n### Option B: VS Code / Antigravity Extension\r\n\r\n1. **Clone and build**\r\n   ```bash\r\n   git clone https://github.com/cogeor/llmem.git\r\n   cd llmem\r\n   npm install\r\n   npm run package\r\n   ```\r\n   This creates a `.vsix` file in the project root.\r\n\r\n2. **(Optional) Add language support** — install grammars for languages you need:\r\n   ```bash\r\n   npm install tree-sitter-python tree-sitter-cpp  # etc.\r\n   ```\r\n\r\n3. **Install the VSIX**\r\n   ```bash\r\n   code --install-extension llmem-0.1.0.vsix\r\n   # or for Antigravity:\r\n   antigravity --install-extension llmem-0.1.0.vsix\r\n   ```\r\n\r\n### Development Mode\r\n\r\nFor contributors:\r\n\r\n1. **Clone and install**\r\n   ```bash\r\n   git clone https://github.com/cogeor/llmem.git\r\n   cd llmem\r\n   npm install\r\n   ```\r\n\r\n2. **Build**\r\n   ```bash\r\n   npm run build:all    # Build both VS Code extension and Claude CLI\r\n   ```\r\n\r\n3. **Run**\r\n   - **VS Code/Antigravity**: Press `F5` to launch Extension Development Host\r\n   - **Claude CLI**: Run `npm run serve` to start the graph server\r\n\r\n## 🎯 Usage Workflow\r\n\r\nLLMem works in two stages: **graph visualization** and **documentation generation** (via MCP tools).\r\n\r\n### Using with Claude Code\r\n\r\n1. **Start the graph server** in your project:\r\n   ```bash\r\n   npm run serve\r\n   ```\r\n   This opens the webview at `http://localhost:5757` with live reload (override with `--port`).\r\n\r\n2. **Toggle watched files** in the left panel — click the circles next to files/folders to include them in the graph.\r\n\r\n3. **Use MCP tools** via Claude:\r\n   - \"Run mcp folder_info on src/graph\"\r\n   - \"Run mcp file_info on src/mcp/tools.ts\"\r\n\r\n### Using with VS Code / Antigravity\r\n\r\n1. **Open the LLMem Panel** via command palette (`Ctrl+Shift+P`):\r\n   ```\r\n   LLMem: Open View Panel\r\n   ```\r\n\r\n2. **Toggle watched files** — grey circles = unwatched, green = watched.\r\n\r\n3. **Use MCP tools** via the IDE's agent.\r\n\r\n### Navigating the Graph\r\n\r\nThe graph displays:\r\n- **Import edges**: File-to-file import dependencies (all languages)\r\n- **Call edges**: Function-to-function call relationships (**TypeScript/JavaScript only**)\r\n\r\n**Controls:**\r\n- Pan: Click and drag\r\n- Zoom: Mouse wheel\r\n- Select: Click a node to highlight connections\r\n\r\n> [!TIP]\r\n> Toggle an entire folder to watch all files within it at once.\r\n\r\n---\r\n\r\n## 💡 MCP Tools Reference\r\n\r\n| Tool | Purpose |\r\n|------|---------|\r\n| `folder_info` | Returns folder structure + an LLM enrichment prompt. **Pair with `report_folder_info`** (process the prompt through your LLM first). |\r\n| `file_info` | Returns file structure + an LLM enrichment prompt. **Pair with `report_file_info`** (process the prompt through your LLM first). |\r\n| `report_folder_info` | Save the LLM-enriched folder doc to `.arch/{folder}/README.md`. |\r\n| `report_file_info` | Save the LLM-enriched file doc to `.arch/{file}.md`. |\r\n| `open_window` | Open the LLMem graph: a `file://` snapshot URL in standalone mode, an integrated panel in VS Code / Antigravity. |\r\n\r\n> [!IMPORTANT]\r\n> MCP documentation tools require the graph to be computed first. Make sure to **toggle watched files** before generating summaries.\r\n\r\n### Generating Spec Docs (Worked Example)\r\n\r\nTo document `src/parser`, the agent runs four steps:\r\n\r\n1. Call `folder_info` with `{ path: \"src/parser\" }` → receives structural payload + LLM enrichment prompt.\r\n2. Process the prompt through its LLM → produces JSON with `overview`, `key_files`, `architecture` (and optional `inputs` / `outputs`).\r\n3. Call `report_folder_info` with that enriched payload → LLMem writes **`.arch/src/parser/README.md`**.\r\n4. Per-file equivalent: `file_info` → LLM → `report_file_info` writes **`.arch/src/parser/<file>.md`** (e.g. `.arch/src/parser/registry.ts.md`).\r\n\r\n> [!NOTE]\r\n> Without an MCP-aware agent, the same pipeline runs from a shell: `llmem document src/parser --prompt-only` prints the prompt; pipe your LLM's JSON response back with `llmem document src/parser --content-file -` to write the `.arch/` doc.\r\n\r\n## 🏗️ Architecture\r\n\r\n```\r\nUser → MCP Agent (Claude Code / Antigravity) → LLMem MCP Server\r\n```\r\n\r\n- **User**: Asks a question about the codebase\r\n- **Agent**: Calls MCP tools to gather context\r\n- **LLMem**:\r\n  1. Parses code using Tree-sitter (TS Compiler API for TypeScript/JavaScript)\r\n  2. Builds import/call graphs from edge list data\r\n  3. Generates documentation prompts for the LLM\r\n  4. Saves documentation to `.arch/` directory\r\n- **Agent**: Uses the context to answer the User\r\n\r\n## 🛠️ Development\r\n\r\n| Command | Description |\r\n|---------|-------------|\r\n| `npm run build:all` | Build everything (VS Code + Claude CLI) |\r\n| `npm run build:vscode` | Build VS Code extension only |\r\n| `npm run build:claude` | Build Claude CLI only |\r\n| `npm run watch` | Watch mode for TypeScript |\r\n| `npm run serve` | Start graph server with live reload |\r\n| `npm test` | Run tests |\r\n\r\n## 📁 Directory Structure\r\n\r\n| Directory | Description |\r\n|-----------|-------------|\r\n| `src/extension` | VS Code/Antigravity IDE integration |\r\n| `src/claude` | Claude Code CLI plugin and graph server |\r\n| `src/mcp` | MCP server implementation and tool handlers |\r\n| `src/parser` | Tree-sitter parsers for code analysis |\r\n| `src/graph` | EdgeList data structures for imports and calls |\r\n| `src/info` | Information extraction for documentation |\r\n| `src/webview` | Interactive graph visualization UI |\r\n| `src/artifact` | Shadow filesystem (`.arch/`) management |\r\n\r\n## Configuration\r\n\r\nLLMem exposes three settings (configurable in VS Code settings or via environment):\r\n\r\n| Setting | Default | Description |\r\n|---------|---------|-------------|\r\n| `artifactRoot` | `.artifacts` | Directory for edge lists and generated webview files |\r\n| `maxFilesPerFolder` | `20` | Maximum files processed per folder analysis |\r\n| `maxFileSizeKB` | `512` | Files larger than this are skipped during analysis |\r\n\r\n### Workspace Root Detection\r\n\r\nThe MCP server determines the workspace root in this priority order:\r\n\r\n1. Root stored in extension context (set when the extension activates)\r\n2. `LLMEM_WORKSPACE` environment variable\r\n3. Auto-detect by walking up from cwd, looking for `.arch`, `.artifacts`, or `package.json`\r\n4. Fallback to current working directory\r\n\r\n### Client Configuration\r\n\r\n**Claude Desktop** — config file location:\r\n- Linux/macOS: `~/.config/claude/claude_desktop_config.json`\r\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"llmem\": {\r\n      \"command\": \"node\",\r\n      \"args\": [\"/absolute/path/to/llmem/dist/claude/index.js\"],\r\n      \"env\": {\r\n        \"LLMEM_WORKSPACE\": \"/absolute/path/to/your/project\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n**Claude Code** — config file location:\r\n- Linux/macOS: `~/.config/claude/config.json`\r\n- Windows: `%APPDATA%\\Claude\\config.json`\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"llmem\": {\r\n      \"command\": \"node\",\r\n      \"args\": [\"/absolute/path/to/llmem/dist/claude/index.js\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n**VS Code** — `.vscode/settings.json` in your project:\r\n\r\n```json\r\n{\r\n  \"llmem.artifactRoot\": \".artifacts\",\r\n  \"llmem.maxFilesPerFolder\": 20,\r\n  \"llmem.maxFileSizeKB\": 512\r\n}\r\n```\r\n\r\n## 📄 License\r\n\r\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\r\n","readmeFilename":"README.md","_rev":"1-846a77d9769816260f3f4a16f0eb4467"}