maku85/vemora

# vemora [](https://www.npmjs.com/package/vemora) [](https://www.npmjs.com/package/vemora?activeTab=versions) [](LICENSE) Repository-local memory system for LLM-assisted development. Builds a structured, versioned index of your codebase — code chunks, symbols, dependency graph, and LLM-generated summaries — and enables semantic or keyword search over it. The result is a **RAG (Retrieval-Augmented Generation) layer** that lets you give an LLM only the code it actually needs, instead of entire files. ## Why When working on a large codebase with Claude Code or similar LLM tools, you face two problems: 1. **Context cost** — dropping 50 files into the context wastes tokens on irrelevant code 2. **Discovery** — you don't always know *which* files are relevant to a given task `vemora` solves both by pre-indexing the repo and making it queryable. It also provides higher-level commands that go beyond retrieval: - **`vemora plan`** — a pro LLM (planner) decomposes a complex task into concrete steps; a smaller/free LLM (executor) carries out each step against targeted code context. Cuts costs by using expensive models only where they matter. - **`vemora audit`** — systematic, checklist-driven analysis of your codebase for security vulnerabilities, performance issues, and bugs. Covers every file, produces structured findings with severity levels. - **`vemora triage`** — zero-LLM static heuristic scan for bugs, security issues, and performance problems. Instant results with no API calls, useful as a first pass before a deeper audit. - **`vemora dead-code`** — zero-LLM static analysis that detects unused private symbols, exports nobody imports, and files that are never imported. Works entirely from the call graph and dependency graph already in the index. - **`vemora focus`** — aggregates all structural context about a file or symbol in one shot: implementation, exports, dependency graph, callers, test files, and saved knowledge. ## Architecture in three layers .vemora/ ← versioned in git, shared across the team config.json metadata.json index/ files.json ← file hashes for incremental indexing chunks.json ← code chunks (function/class/window slices) symbols.json ← extracted symbol map deps.json ← intra-project dependency graph callgraph.json ← function-level call relationships todos.json ← TODO/FIXME/HACK/XXX annotations extracted from source summaries/ file-summaries.json ← LLM-generated 2-3 line description per file project-summary.json ← LLM-generated ~500 word project overview knowledge/ entries.json ← human/LLM-authored notes: decisions, gotchas, patterns ~/.vemora-cache// ← local to each developer, NOT in git embeddings.json ← metadata (model, dimensions, chunk mapping) embeddings.bin ← binary buffer of vectors (Float32Array) embeddings.hnsw.json ← serialized HNSW index for ultra-fast search The index, summaries, and knowledge entries are committed to git so teammates share them. Embeddings are generated locally by each developer from the shared index. ## Installation # Inside the vemora/ directory pnpm install pnpm build # Link globally (optional) pnpm link Or run directly with `node vemora/dist/cli.js` from the project root. ### Installing the alpha version from npm pnpm install vemora@alpha # local pnpm install -g vemora@alpha # global # or with npm: npm install -g vemora@alpha ## The Core Workflow ### 1. Setup (first time only) vemora init # create .vemora/ and config.json vemora index --no-embed # build index without embeddings (fast) vemora index # or: build index + generate embeddings vemora summarize # recommended: generate LLM descriptions per file vemora init-agent # generate instruction files for AI agents vemora init-agent --hooks # also write Claude Code auto-save hooks ### 1b. Start of each session (CLI mode) vemora brief --root . # compact primer: project overview + critical knowledge ### 1c. MCP server mode (Claude Desktop / Claude Code) Install the SDK once, then start the server: npm install @modelcontextprotocol/sdk vemora mcp --root . Add to `.claude/settings.json` (Claude Code) or `claude_desktop_config.json` (Claude Desktop) — see [`vemora mcp`](#vemora-mcp) for full config. In MCP mode, the agent calls `search`, `focus`, `brief`, `remember`, and `deps` as native tools without manual `vemora context` invocations. ### 2. Query during development # Search for relevant code vemora query "how does IMAP reconnect work?" # Full context block ready to paste into any LLM vemora context --query "email retry logic" > context.md # Context with a task-type skill preset (pre-configures retrieval + adds focus note) vemora context --query "auth flow fails silently" --skill debug vemora context --query "extract retry logic to utility" --skill refactor vemora context --query "add webhook support" --skill add-feature # One-shot answer from the configured LLM vemora ask "why does the sync queue stall?" # All context about a file or symbol in one call (no LLM needed) vemora focus src/core/email/services/email.service.ts vemora focus EmailService.send # Static scan for bugs/perf/security (no API key required) vemora triage --type bugs,performance # Save a finding for future sessions vemora remember "EmailService.send queues if SMTP is offline — see OutboxRepository" ### 3. Complex tasks with the planner-executor pattern # Pro LLM plans, small/free LLM executes each step vemora plan "add rate limiting to the API layer" --confirm --synthesize # Audit the codebase for issues vemora audit --type security --root . vemora audit --since HEAD~1 # only changed files (great for CI) ### 4. Keep the index fresh vemora index --watch # incremental re-index on file save vemora index --no-embed # after code changes, update structure only ## Commands ### `vemora init` Creates the `.vemora/` folder structure and adds `.vemora-cache/` to `.gitignore`. Options: --root project root (default: cwd) ### `vemora index` Scans the repo, parses symbols, builds the dependency graph, extracts TODO/FIXME/HACK/XXX annotations, and generates embeddings. **Incremental** — only re-processes files whose SHA-256 hash has changed. If LLM-generated summaries exist (from `vemora summarize`), each summary is also embedded as a synthetic file-overview chunk. This allows abstract queries ("how does authentication work?") to match against natural-language descriptions rather than raw code. Options: --root project root (default: cwd) --force re-index all files, ignoring hashes --no-embed skip embedding generation (index structure only) -w, --watch watch for changes and re-index automatically ### `vemora query ""` Searches the index using vector similarity (or keyword fallback). Results use a **three-tier display** that compresses output by relevance rank. Options: --root project root (default: cwd) -k, --top-k number of results (default: 10) -c, --show-code show full code for all results (overrides tier system) --keyword force keyword/BM25 search (no API call needed) --format output format: terminal (default) | json | markdown | terse --rerank re-score results with a cross-encoder model --hybrid use hybrid search (vector + BM25) --alpha hybrid weight for vector search (0-1, default 0.7) --budget max tokens to include across results --mmr apply Maximal Marginal Relevance to diversify results --lambda MMR relevance weight (0=diverse, 1=relevant, default 0.5) --merge merge adjacent chunks from the same file --merge-gap max line gap between chunks to still merge (default 3) --centrality boost results from widely-imported files (dep-graph centrality) --session enable session tracking: demote already-seen chunks (×0.3) and compress seen-file chunks to signature only (auto-expires after 30 min idle) --fresh reset session memory before this query (implies --session) #### Output formats | Format | Use case | |---|---| | `terminal` | Default coloured output for interactive use | | `json` | Machine-readable — for piping to scripts | | `markdown` | Paste-ready Markdown with code blocks | | `terse` | One line per result — recommended for small/local models | #### Output tiers (terminal/markdown) | Rank | Tier | Content shown | |------|------|--------------| | 1–3 | high | Full code block (capped at 30 lines) | | 4–7 | med | Declaration signature only | | 8+ | low | File path + symbol + score + AI summary | ### `vemora context` Generates an **optimized LLM context block** combining project overview, a specific file, and relevant code chunks. Designed to be piped to a file or clipboard. Options: --root project root (default: cwd) -q, --query natural-language query to find relevant code -f, --file include a specific file in full with its dependency graph -k, --top-k number of search results to include (default: 5) --keyword use keyword search instead of semantic search --show-code show full code without line cap --format output format: markdown (default) | plain | terse --rerank re-score results with a cross-encoder model --hybrid use hybrid search (vector + BM25) --alpha hybrid weight for vector search (0-1, default 0.7) --budget max tokens to include across retrieved chunks --mmr apply Maximal Marginal Relevance to diversify results --lambda MMR relevance weight (0=diverse, 1=relevant, default 0.5) --merge merge adjacent or overlapping chunks from the same file --merge-gap max line gap between chunks to still merge (default 3) --structured emit a structured block (Entry Point / Dependencies / Types / Patterns) --since restrict search to files changed since this git ref (e.g. HEAD~5, main) --skill task-type preset — pre-configures retrieval and prepends a focused instruction block (debug | refactor | add-feature | security | explain | test) --centrality boost results from widely-imported files (dep-graph centrality) --session enable session tracking: demote already-seen chunks and compress seen-file chunks to signature only (auto-expires after 30 min idle) --fresh reset session memory before this query (implies --session) At least one of `--query` or `--file` is required. When `--file` is used, the context block also includes: - **Recent git commits** that touched the file (last 5, via `git log --follow`) - **TODO/FIXME/HACK/XXX annotations** present in the file - **Test files** linked to the file — convention-based and import-based discovery - **Symbol callers** — for each symbol defined in the file, which other project symbols call it #### Skills (`--skill`) A skill is a **task-type preset** that does two things at once: 1. **Pre-configures the retrieval pipeline** — sets task-appropriate defaults for `topK`, `hybrid`, `mmr`, `budget`, and `structured` so you don't need to tune flags manually. 2. **Prepends a focused instruction block** to the output — tells the LLM exactly what kind of reasoning to apply (error paths, blast radius, code style, etc.). Explicit flags always override skill defaults. | Skill | Best for | Key retrieval changes | |---|---|---| | `debug` | Tracing errors, call paths, exception handling | topK 8, hybrid (BM25 for error strings), high MMR relevance | | `refactor` | Safe minimal-diff changes | structured output (callers explicit), topK 6 | | `add-feature` | Adding new functionality following existing patterns | structured + high MMR diversity to surface varied patterns | | `security` | Security review, injection, auth, path traversal | BM25-heavy (α=0.55), boosts `gotcha` knowledge entries | | `explain` | Understanding purpose and design decisions | Maximum MMR diversity (λ=0.4), lower budget | | `test` | Writing or improving tests | hybrid search, surfaces test file patterns | vemora context --root . --query "auth flow fails silently" --skill debug vemora context --root . --query "extract retry logic to utility" --skill refactor vemora context --root . --query "add webhook support" --skill add-feature #### Session tracking (`--session`) When `--session` is active, vemora maintains a per-project session file (`~/.vemora-cache//session.json`) that tracks which chunks and files have already been returned. On subsequent queries, rather than hard-filtering seen results: - **Chunk decay** — already-seen chunk scores are multiplied by 0.3, so they remain candidates if genuinely re-relevant but don't dominate fresh results. - **Signature compression** — chunks from files already seen in this session have their content replaced with just the declaration signature, saving tokens without losing location context. Sessions auto-expire after 30 minutes of idle time. Use `--fresh` to reset explicitly. vemora query "error handling" --session --root . # first query: full results vemora query "logging setup" --session --root . # seen chunks demoted, seen files compressed vemora query "error handling" --fresh --root . # reset session, start fresh ### `vemora ask ""` One-shot Q&A: retrieves relevant context and calls the configured LLM to answer directly. Options: --root project root (default: cwd) -k, --top-k chunks to retrieve (default: 5) --keyword use keyword search (no embeddings needed) --hybrid use hybrid vector+BM25 search --budget max context tokens to send to LLM (default: 6000) --show-context print the retrieved context before the answer --terse inject brevity constraint into LLM system prompt (~50-70% fewer output tokens) vemora ask "how does the IMAP reconnect logic work?" --root . vemora ask "what does EmailService.send do?" --root . --keyword ### `vemora plan ""` **Planner-executor pattern**: a capable LLM decomposes the task into a structured plan; a smaller/cheaper LLM executes each step against targeted code context. The planner works from **file summaries and the symbol list** — not raw code — so its token cost stays low regardless of codebase size. The executor receives only the chunks relevant to its specific step (targeted by file/symbol, not just search). Options: --root project root (default: cwd) -k, --top-k chunks to retrieve per step when falling back to search (default: 5) --keyword use keyword search (no embeddings required) --budget max context tokens per step (default: 4000) --confirm show the plan and ask for confirmation before executing --synthesize call the planner again after all steps to produce a single final answer --show-context print retrieved context for each step --verify after each executor step, have the planner review the output --apply automatically apply unified diffs produced by write steps (via patch -p1) --max-retries max re-runs of a step when verification fails (default: 2) --resume resume a previous session by short ID (first 8 chars) or full UUID --terse inject brevity constraint into executor analyze and synthesis prompts (~50-70% fewer output tokens) #### Step action types | Action | Behaviour | |---|---| | `read` | Pull code into context — no LLM call, zero executor tokens | | `analyze` | Executor answers a question in prose | | `write` | Executor produces a unified diff ready to apply | | `test` | Run a shell command; capture stdout/stderr as step result | #### Key features - **Parallel execution** — steps without dependencies run concurrently; sequential steps stream tokens to stdout in real time - **Step dependencies** (`dependsOn`) — later steps receive prior results as context - **Context deduplication** — the same file/symbol combination is retrieved only once per session - **Adaptive re-planning** — if an executor step reports insufficient context (`INSUFFICIENT:`), vemora first retries with a refined BM25 search derived from the missing-context description; only if that also fails does it invoke the planner to add remediation steps - **Planner verification** (`--verify`) — after each executor step, the planner reviews the output and can request a retry with specific feedback - **Diff application** (`--apply`) — diffs from `write` steps are applied to the filesystem via `patch -p1`; live file contents are read before write steps to avoid stale index data - **Session persistence** — every session is saved to `~/.vemora-cache//sessions/` after each wave; interrupted runs can be resumed with `--resume ` - **Save synthesis** — after `--synthesize`, optionally save the result as a knowledge entry # Plan, preview, and execute with final synthesis vemora plan "add batch() method to OpenAIEmbeddingProvider" --confirm --synthesize # Analysis only (no code changes) vemora plan "explain how the hybrid search pipeline works" --keyword # Executor writes diffs, planner verifies each step, apply to disk vemora plan "fix the N+1 query in UserRepository.findAll" --verify --apply # Resume an interrupted session (use vemora sessions to find the ID) vemora plan "..." --resume a1b2c3d4 #### Configuration { "planner": { "provider": "anthropic", "model": "claude-opus-4-6" }, "executor": { "provider": "ollama", "model": "qwen2.5-coder:14b", "baseUrl": "http://localhost:11434" } } `executor` is the model that carries out each step. If `executor` is omitted, `summarization` is used as the fallback. If `planner` is omitted, both roles use the same model. ##### Using Claude Code as the planner Set `provider: "claude-code"` to use the local `claude` CLI subprocess as the planner. The subprocess can autonomously explore the codebase with `Read`, `Grep`, and `Glob` tools before generating the plan: { "planner": { "provider": "claude-code", "model": "claude-sonnet-4-6", "baseUrl": "/path/to/claude", "allowedTools": ["Read", "Grep", "Glob"], "maxBudgetUsd": 0.50 } } `baseUrl` is the path to the `claude` binary (default: `"claude"`, assumed on `PATH`). ### `vemora sessions` Lists recent plan sessions for the current project, showing their short ID, status, creation date, and task preview. vemora sessions --root . Use the short ID printed here with `vemora plan "" --resume ` to continue an interrupted run. ### `vemora audit` Systematic, checklist-driven code audit for **security vulnerabilities**, **performance issues**, and **bugs**. Covers every file in the codebase (or only changed files with `--since`). Options: --root project root (default: cwd) --type comma-separated: security, performance, bugs (default: all three) --since only audit files changed since this git ref (e.g. HEAD~5, main) --budget max context tokens per step (default: 5000) --keyword use keyword search (no embeddings required) --output terminal (default) | json | markdown --save save critical/high findings as knowledge entries #### Built-in checklists | Type | Examples | |---|---| | `security` | SQL/command/path injection, hardcoded secrets, weak crypto, missing auth/authz, XSS, CSRF, prototype pollution | | `performance` | N+1 queries, sync I/O in async context, unbounded data loading, memory accumulation, blocking event loop | | `bugs` | Null dereference, unhandled promise rejections, race conditions, resource leaks, swallowed errors, off-by-one | #### How it works 1. The **planner** receives the file list + summaries and generates a systematic audit plan, grouping 2-5 related files per step with specific checklist items. 2. Steps execute in **parallel waves of 3** — the executor returns structured JSON findings for each group. 3. Findings are **deduplicated, sorted by severity**, and displayed as a report. 4. `--save` persists critical/high findings to the knowledge store for future sessions. # Full audit vemora audit --root . # Security only vemora audit --type security --root . # Audit only what changed in the last commit (ideal for CI/CD) vemora audit --since HEAD~1 --root . # Audit changes vs main branch, save findings vemora audit --since main --type security,bugs --save --root . # Export for a PR review vemora audit --since main --output markdown --root . > audit-report.md #### Example output ── Audit Report [security] ───────────────────────────── 12 file(s) analysed · 3 finding(s) [CRITICAL] Injection src/api/users.ts:89 User input concatenated directly into SQL query without parameterization. → Use parameterized queries or a query builder. [HIGH] Hardcoded Secret src/config.ts:12 API key hardcoded in source — will be exposed in version control. → Move to environment variables and rotate the key. [MEDIUM] Missing Authorization src/api/admin.ts:34 Admin endpoint does not verify that the caller has the admin role. → Add role check before processing the request. ───────────────────────────────────────────────────────── 1 critical · 1 high · 1 medium ### `vemora remember ""` Saves a persistent knowledge entry to `.vemora/knowledge/entries.json`. The entry is committed to git and included automatically in future `context` and `ask` results when relevant. When `--category` is omitted, the configured LLM classifies the entry automatically into one of the four categories. Falls back to `pattern` if no LLM is available. Options: --root project root (default: cwd) --category decision | pattern | gotcha | glossary (auto-classified if omitted) --files comma-separated related file paths --symbols comma-separated related symbol names --confidence high | medium | low (default: medium) --supersedes invalidate an existing entry and link this one as its replacement # Category auto-classified by the LLM vemora remember "EmailService.send queues if SMTP offline — see OutboxRepository" # Or specify explicitly vemora remember "EmailService.send queues if SMTP offline — see OutboxRepository" \ --category gotcha \ --files src/core/email/services/email.service.ts \ --symbols EmailService.send # Replace an existing entry (invalidates abc12345, creates a linked replacement) vemora remember "Updated behaviour: EmailService.send now retries 3×" --supersedes abc12345 ### `vemora brief` Prints a compact session primer — project overview and knowledge entries (medium + high confidence) — designed to be run at the start of each LLM session to re-establish context with minimal tokens. Options: --root project root (default: cwd) --all include all knowledge entries, including low-confidence ones --skill task-type preset: surfaces knowledge entries most relevant to the skill's category boost list and prepends a focused instruction block (debug | refactor | add-feature | security | explain | test) vemora brief --root . # overview + medium & high-confidence entries vemora brief --root . --skill debug # gotcha + pattern entries first, debug focus note vemora brief --root . --skill security # security gotchas surfaced first vemora brief --root . --all # all entries, no filter ### `vemora knowledge` Manages saved knowledge entries. vemora knowledge list --root . # list all entries grouped by category vemora knowledge update "" --root . # edit an existing entry in-place vemora knowledge forget --root . # remove an entry by ID (prefix match) `knowledge update` replaces the body of an existing entry without creating a new one — use it to correct a typo or refine wording. For a change in meaning, prefer `remember … --supersedes ` to preserve history. Options for knowledge update: --root project root (default: cwd) --title