{"_id":"@caiquebrito/nodum","_rev":"5-a82233019773ce7f89811044fa8ed0c5","name":"@caiquebrito/nodum","dist-tags":{"latest":"1.1.1"},"versions":{"1.1.0":{"name":"@caiquebrito/nodum","version":"1.1.0","keywords":["claude","rag","knowledge-graph","code-analysis","dependency-graph","ast-parser"],"author":{"name":"Caique Brito"},"license":"MIT","_id":"@caiquebrito/nodum@1.1.0","maintainers":[{"name":"caiquebrito","email":"caique.brito.ads@gmail.com"}],"homepage":"https://github.com/caiquebrito/nodum#readme","bugs":{"url":"https://github.com/caiquebrito/nodum/issues"},"dist":{"shasum":"5721674e5bfbe4578089439fe41c909c6c76d162","tarball":"https://registry.npmjs.org/@caiquebrito/nodum/-/nodum-1.1.0.tgz","fileCount":72,"integrity":"sha512-J4lT9zaj0eLdWMqzU9EqN/hx0q15/1fJxb2igkRy0T72a34nriD+YUVlwLJ4PEXtYorvtjY+dtbeeIIOuwg74w==","signatures":[{"sig":"MEUCIQC9OCwMAjQ0tKbYMZQtDrt3jjbt0Ko9/aTpYojEIq0w0gIgZOeqNVd7DHJr4l66gQnuLws1aTbKGI9D3YzpUffRFIg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":254295},"type":"module","engines":{"node":">=16.0.0"},"gitHead":"10f8ee6ee6ab1f1b4785e71a30e307faf03bd779","private":false,"scripts":{"dev":"npm run dev --workspaces","lint":"eslint packages --ext .ts","test":"npm run test --workspaces","build":"npm run build:core && npm run build:cli && npm run build:server && npm run build:mcp","clean":"rm -rf packages/*/dist && rm -rf dist","prepare":"npm run build","build:cli":"cd packages/cli && npm run build","build:mcp":"cd packages/mcp && npm run build","build:core":"cd packages/core && npm run build","build:server":"cd packages/server && npm run build"},"_npmUser":{"name":"caiquebrito","email":"caique.brito.ads@gmail.com"},"repository":{"url":"git+https://github.com/caiquebrito/nodum.git","type":"git"},"workspaces":["packages/core","packages/cli","packages/server","packages/mcp"],"_npmVersion":"11.12.1","description":"Local knowledge graph for Claude — scan code, build interactive 3D dependency graph, inject context into CLAUDE.md","directories":{},"_nodeVersion":"25.9.0","_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.50.0","vitest":"^1.0.0","typescript":"^5.3.0","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/nodum_1.1.0_1780272430828_0.5519982822547522","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@caiquebrito/nodum","version":"1.1.1","description":"Local knowledge graph for Claude — scan code, build interactive 3D dependency graph, inject context into CLAUDE.md","type":"module","private":false,"engines":{"node":">=16.0.0"},"scripts":{"build:core":"cd packages/core && npm run build","build:cli":"cd packages/cli && npm run build","build:server":"cd packages/server && npm run build","build:mcp":"cd packages/mcp && npm run build","build":"npm run build:core && npm run build:cli && npm run build:server && npm run build:mcp","dev":"npm run dev --workspaces","test":"npm run test --workspaces","lint":"eslint packages --ext .ts","clean":"rm -rf packages/*/dist && rm -rf dist","prepare":"npm run build"},"workspaces":["packages/core","packages/cli","packages/server","packages/mcp"],"keywords":["claude","rag","knowledge-graph","code-analysis","dependency-graph","ast-parser"],"author":{"name":"Caique Brito"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/caiquebrito/nodum.git"},"devDependencies":{"@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.50.0","typescript":"^5.3.0","vitest":"^1.0.0"},"gitHead":"79e14ade239167b39131e393d4717821d65ca336","_id":"@caiquebrito/nodum@1.1.1","bugs":{"url":"https://github.com/caiquebrito/nodum/issues"},"homepage":"https://github.com/caiquebrito/nodum#readme","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-XyotaGGsXPBMfr3vqzybaoyxeucsv1+7Wi/SOg9UGlwb4BRYg0lJR5FhxSM/Hntn9Dhy8e8hx+HUBKFthauYnQ==","shasum":"36964d4a54705aa7e37b5193d9516611e965bb5b","tarball":"https://registry.npmjs.org/@caiquebrito/nodum/-/nodum-1.1.1.tgz","fileCount":73,"unpackedSize":259991,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHbLVD9+wxhPhlThiIG5BL9CX3aqysbFD0E3Ft67Tq/gAiEAydChRsoZkGjL7YeuLIj7BFjiur5U8pVTS2Bs8mKUHyE="}]},"_npmUser":{"name":"caiquebrito","email":"caique.brito.ads@gmail.com"},"directories":{},"maintainers":[{"name":"caiquebrito","email":"caique.brito.ads@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nodum_1.1.1_1780272776714_0.4563341971603907"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-01T00:07:10.645Z","modified":"2026-06-01T00:12:56.977Z","1.0.0":"2026-05-31T23:59:22.442Z","1.1.0":"2026-06-01T00:07:10.963Z","1.1.1":"2026-06-01T00:12:56.866Z"},"bugs":{"url":"https://github.com/caiquebrito/nodum/issues"},"author":{"name":"Caique Brito"},"license":"MIT","homepage":"https://github.com/caiquebrito/nodum#readme","keywords":["claude","rag","knowledge-graph","code-analysis","dependency-graph","ast-parser"],"repository":{"type":"git","url":"git+https://github.com/caiquebrito/nodum.git"},"description":"Local knowledge graph for Claude — scan code, build interactive 3D dependency graph, inject context into CLAUDE.md","maintainers":[{"name":"caiquebrito","email":"caique.brito.ads@gmail.com"}],"readme":"# nodum — Local Code Memory for Claude\n\n> A self-hosted knowledge graph that gives Claude persistent memory about your projects — with an interactive 3D visualizer.\n\n![Knowledge Graph](https://img.shields.io/badge/viewer-3D_graph-58a6ff?style=flat-square)\n![Python](https://img.shields.io/badge/python-3.9+-3fb950?style=flat-square)\n![License](https://img.shields.io/badge/license-MIT-bc8cff?style=flat-square)\n![No cloud](https://img.shields.io/badge/cloud-none-ff9f1a?style=flat-square)\n![Made in Brazil](https://img.shields.io/badge/made%20in-Brazil%20🇧🇷-009c3b?style=flat-square)\n\n---\n\n## The Problem\n\nEvery time you open a new Claude Code session, it starts from scratch. You explain your stack again. Re-describe the architecture. Paste the same file paths over and over. Claude is smart, but it has no memory — and this constant re-explanation wastes time and breaks your train of thought.\n\nThe common solution is to dump everything into `CLAUDE.md`. But that becomes a mess quickly: no structure, no automation, outdated as soon as the code changes, and you still write it all manually.\n\n---\n\n## The Idea\n\nWhat if Claude always knew about your project — the files, functions, dependencies, the decisions you made last week — without you needing to explain it again?\n\nThat's what nodum does. A **local knowledge graph** that lives alongside your projects:\n\n- Scans your code and builds a structured map of files, functions, classes, and imports\n- Automatically detects your stack (Android, Kotlin, Python, Go, Rust, Docker…) and generates a project summary\n- Maintains session logs — what Claude worked on each day, what was decided, what's next\n- Injects context into `CLAUDE.md` so Claude reads the graph before answering **anything**\n- Serves an **interactive 3D visualizer** — orbit, zoom, click nodes, see connections live\n\nEverything runs locally. No API calls, no cloud, no subscription.\n\n---\n\n## How It Works\n\nThe goal was to keep it simple — no frameworks, no build step, no package managers. Just Python and vanilla JS.\n\nThe sync script (`scripts/sync.py`) reads your project files using Python's `ast` module for Kotlin/Java and regex patterns for other languages. It traverses the directory tree, extracts nodes (files, functions, classes) and edges (imports, definitions), and writes a `graph.json`. It also reads config files — `build.gradle`, `AndroidManifest.xml`, `settings.gradle`, `.env.example` — and generates a `SUMMARY.md` with stack, build variants, and environment variables already filled in.\n\nThe visualizer (`viewer/app.js`) uses [3d-force-graph](https://github.com/vasturiano/3d-force-graph) — a 3D force-directed graph in WebGL — to render your code as a living atom you can orbit and explore. Nodes are sized by connection count. Import edges have animated particles flowing through them. Click a node and a detail panel slides in showing everything it imports and everything that uses it.\n\nThe injection into `CLAUDE.md` forces Claude to print a formatted context block at the start of each session — stack, file count, last sync date, project summary — before answering anything.\n\n---\n\n## Demo\n\n```\n┌─ nodum Viewer (localhost:7842) ────────────────────────────────────┐\n│                                                                      │\n│  [Explorer]        [  ●  3D graph — orbit with mouse  ●  ]         │\n│  ▼ app                                                               │\n│    ▼ ui            Nodes glow by group: ui · service · model        │\n│      MainActivity.kt 12  Particles flow along import edges          │\n│        ƒ onCreate     Click a node → detail panel slides in         │\n│        ƒ setupViews                                                 │\n│    ▶ services    [ Logs ]   ── daily session logs ──                │\n│    ▶ models      [ Memory ] ── SUMMARY.md of project ──             │\n└──────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Project Structure\n\n```\nnodum/                        ← this repository\n│\n├── scripts/\n│   ├── sync.py                ← scans a project and saves the data\n│   └── graph_gen.py           ← AST parser (Kotlin/Java/Python/JS)\n│\n├── viewer/                    ← 3D visualizer (served via HTTP)\n│   ├── index.html\n│   ├── app.js\n│   └── style.css\n│\n├── projects.json              ← index of all synced projects\n│\n└── <project-name>/            ← one folder per project\n    ├── graph/graph.json       ← code graph (auto-generated)\n    ├── memory/SUMMARY.md      ← project summary (generated + editable)\n    └── logs/\n        ├── activity.md        ← sync history\n        └── 2024-01-15.md      ← daily session log\n\n<your-project>/               ← your actual project (not modified)\n    └── CLAUDE.md              ← RAG context injected here\n```\n\nYour actual projects **are never modified**, except for `CLAUDE.md`.\n\n---\n\n## Quick Start\n\n### 1. Clone this repo\n\n```bash\ngit clone https://github.com/caiquebrito/nodum ~/path/to/nodum\ncd ~/path/to/nodum\n```\n\nNo dependencies to install — just Python 3.9+ (standard library only).\n\n### 2. Sync a project\n\n```bash\npython3 scripts/sync.py /path/to/your/android/project\n```\n\nThis will:\n- Parse all `.kt`, `.java`, `.gradle`, `.py`, `.js`, `.ts` files and generate the graph\n- Auto-detect the stack from `build.gradle`, `package.json`, `pyproject.toml`, etc.\n- Create `<project>/memory/SUMMARY.md` pre-filled with stack, build variants, and dependencies\n- Write a `CLAUDE.md` in your project forcing Claude to load context each session\n- Create a daily log in `<project>/logs/YYYY-MM-DD.md`\n\n### 3. Start the visualizer\n\n```bash\npython3 serve.py\n```\n\nOpens `http://localhost:7842/` automatically. The 3D graph is interactive:\n- **Drag** to orbit, **scroll** to zoom\n- **Click** a node to see its connections in the detail panel\n- **Hover** for tooltip with name, type, and file path\n- **Sidebar** shows the real folder tree with functions nested under files\n- **Sync button** rescans the current project's code (no terminal needed)\n- **Memory button** shows the SUMMARY.md of the project\n- **Logs button** navigates through daily session logs\n\n### 4. Check project status\n\n```bash\npython3 scripts/sync.py --status\n```\n\n---\n\n## Integration with Claude Code\n\nAfter syncing, your project's `CLAUDE.md` will contain:\n\n```markdown\n## Knowledge Graph Context — Required\n\nABSOLUTE RULE: at the start of each session, BEFORE answering anything, you MUST:\n\n1. Read the files listed below in order\n2. Print a context block:\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n  Knowledge Graph loaded: myapp\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n  Stack:      Android · Kotlin · Jetpack Compose\n  Files:      127 files · 84 classes · 312 functions\n  Last sync:  2024-01-15 14:32\n  Memory:     Mobile app for tracking user workouts...\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\nClaude reads the graph, memory, and logs **before each response** — and always knows the project without re-explaining.\n\n### Skills for Claude Code\n\nThe `/rag-sync` skill is available for use during Claude Code sessions. More details and improvements coming soon.\n\n#### Installing Skills\n\nNodum includes ready-to-use Claude Code skills in the `claude-skills/` folder. To use them in your project:\n\n1. Copy the skills from nodum into your project's `.claude` folder:\n   ```bash\n   cp -r /path/to/nodum/claude-skills/* /path/to/your/project/.claude/\n   ```\n\n2. Skills are now available as slash commands (e.g., `/rag-sync`) during your Claude Code sessions.\n\nIf `.claude` folder doesn't exist in your project, Claude Code will create it automatically on first use.\n\n---\n\n## Automatically Detected Stack\n\nThe `sync.py` reads your project files and populates `memory/SUMMARY.md` automatically:\n\n| File | What gets detected |\n|------|-------------------|\n| `build.gradle` | Language (Kotlin/Java), Android version, libraries, build flavors |\n| `AndroidManifest.xml` | App name, permissions, Activities, Services |\n| `settings.gradle` | Module structure and dependencies |\n| `package.json` | Runtime (Node/Bun), language (TS/JS), frameworks (React, Next, Express…), ORMs, libraries |\n| `pyproject.toml` / `requirements.txt` | Python + FastAPI / Django / Flask / SQLAlchemy |\n| `go.mod` | Go + Gin / Echo / Fiber |\n| `Cargo.toml` | Rust |\n| `docker-compose.yml` | Docker Compose services |\n| `.env.example` | All environment variable names |\n| `Makefile` | Available `make` targets |\n| `README.md` | First paragraph as project description |\n\nSections that can't be auto-detected (`## Dependencies On`, `## Exposes To`, `## Notes`) are left blank for you to fill.\n\n---\n\n## Supported Languages\n\n| Language | Extensions | What gets extracted |\n|----------|-----------|-----------------|\n| Kotlin | `.kt` | imports, functions, classes, objects |\n| Java | `.java` | imports, methods, classes |\n| JavaScript | `.js`, `.mjs`, `.cjs` | imports, functions, classes |\n| TypeScript | `.ts`, `.tsx` | imports, functions, classes, interfaces |\n| JSX | `.jsx` | imports, functions, components |\n| Python | `.py` | imports, functions, classes (via AST) |\n\n---\n\n## Project Memory Structure\n\n```\n<project-name>/\n├── graph/\n│   └── graph.json          # nodes (file/function/class) + edges (imports/defines)\n├── memory/\n│   └── SUMMARY.md          # auto-generated, freely editable\n└── logs/\n    ├── activity.md         # each sync recorded here\n    ├── 2024-01-15.md       # daily session log (created by /rag-sync)\n    └── 2024-01-16.md\n```\n\n### graph.json Format\n\n```json\n{\n  \"project\": \"myapp\",\n  \"stats\": { \"files\": 127, \"functions\": 312, \"classes\": 84, \"edges\": 498 },\n  \"nodes\": [\n    { \"id\": \"app_ui_MainActivity_kt\", \"label\": \"MainActivity.kt\", \"type\": \"file\",\n      \"file\": \"app/ui/MainActivity.kt\", \"group\": \"ui\" },\n    { \"id\": \"app_ui_MainActivity_kt__onCreate\", \"label\": \"onCreate\", \"type\": \"function\",\n      \"file\": \"app/ui/MainActivity.kt\", \"group\": \"ui\" }\n  ],\n  \"edges\": [\n    { \"source\": \"app_ui_MainActivity_kt\", \"target\": \"app_services_LocationService_kt\",\n      \"relation\": \"imports\" }\n  ]\n}\n```\n\n### Node Groups\n\n| Group | Directories |\n|-------|-----------|\n| `ui` | `ui/`, `fragments/`, `activities/`, `screens/` |\n| `service` | `services/`, `service/` |\n| `model` | `models/`, `data/`, `entities/`, `schema/` |\n| `repo` | `repository/`, `repositories/` |\n| `util` | `utils/`, `helpers/`, `lib/`, `common/` |\n| `config` | `config/`, `settings/`, `di/` |\n| `test` | `test/`, `tests/`, `androidTest/`, `unitTest/` |\n\n---\n\n## Visualizer Features\n\n- **3D force graph** — nodes repel each other, camera orbits freely (WebGL via three.js)\n- **Auto-fit on load** — graph always fits when switching projects\n- **Size by degree** — more connected nodes appear larger\n- **Animated particles on import edges** — points flow along dependency arrows\n- **Sidebar with file tree** — same folder structure, functions nested under files\n- **Project selector** — dropdown supporting unlimited projects\n- **Sync button** — rescans code without leaving the interface (runs sync.py automatically)\n- **Memory panel** — click Memory to read the SUMMARY.md\n- **Session logs** — click Logs to browse daily session logs\n- **Search** — find any function, file, or class in the graph\n- **Detail panel** — click a node to see what it imports and what uses it\n- **Export PNG** — download a screenshot of the current view\n- **Auto-rotation** — smooth orbit when idle, pauses on interaction\n\n---\n\n## Command Reference\n\n```bash\n# Sync a project (create or update all data)\npython3 scripts/sync.py /path/to/your/project\n\n# Start the 3D visualizer on localhost:7842\npython3 serve.py\n\n# Check all synced projects with stats\npython3 scripts/sync.py --status\n```\n\n| File | Written by | Contains |\n|------|-----------|----------|\n| `graph/graph.json` | sync (auto) | Code graph |\n| `memory/SUMMARY.md` | sync + you | Project summary |\n| `logs/activity.md` | sync (auto) | Sync history |\n| `logs/YYYY-MM-DD.md` | Claude (`/rag-sync`) | Daily session log |\n| `projects.json` | sync (auto) | Project index |\n\n---\n\n## Ignoring Files\n\nThe scanner ignores these directories by default:\n\n```\nnode_modules  .git  dist  build  .next  __pycache__  coverage\n.gradle  build/  .idea/  .DS_Store\n```\n\n---\n\n## Contributing\n\nPRs welcome. The code is intentionally simple — no build step, no package manager, no framework.\n\n```\nscripts/sync.py       ~330 lines  — orchestrator\nscripts/graph_gen.py  ~200 lines  — AST parser\nviewer/app.js         ~600 lines  — 3D visualizer (vanilla JS)\nviewer/style.css      ~400 lines  — dark theme\nserve.py               ~30 lines  — local HTTP server\n```\n\n---\n\n## Author\n\nFeito com foco por **Caique Brito** — 🇧🇷 Brasil.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}