# ๐Ÿง  Lemma [![npm version](https://img.shields.io/npm/v/@nxuss/lemma.svg?color=orange&style=flat-square)](https://www.npmjs.com/package/@nxuss/lemma) [![License](https://img.shields.io/npm/l/@nxuss/lemma.svg?color=blue&style=flat-square)](https://github.com/Nxusbets/lemma/blob/main/LICENSE) [![MCP Tools](https://img.shields.io/badge/MCP%20tools-109-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma) [![Security](https://img.shields.io/badge/privacy-firewall%20active-blueviolet?style=flat-square)](https://github.com/Nxusbets/lemma) [![Caching](https://img.shields.io/badge/semantic%20memory-enabled-success?style=flat-square)](https://github.com/Nxusbets/lemma) [![Tests](https://img.shields.io/badge/tests-919%20passing-00c853?style=flat-square)](https://github.com/Nxusbets/lemma) ```text __ / / ___ ____ ___ ____ ___ ____ _ / / / _ \/ __ `__ \/ __ `__ \/ __ `/ / /___/ __/ / / / / / / / / / / /_/ / /_____/\___/_/ /_/ /_/_/ /_/ /_/\__,_/ ``` > **The Intelligent local-first AI Gateway โ€” Privacy, Performance, Static Code Intelligence, and Infrastructure Command Center for the Agentic Era.** Lemma sits between your development environment and LLM providers as an MCP server / local proxy. It cuts what actually enters the model's context โ€” repeated reads, unfiltered command output, tool schemas the project can't use โ€” while keeping every answer verifiable: a cache hit is disclosed as a cache hit, a compressed file is never what the user sees, and a savings number always traces back to an auditable ledger, never an estimate. ## ๐Ÿš€ Quick start ```bash npm install -g @nxuss/lemma lemma init # auto-configures MCP for your IDE (Muse, Claude Code, Cursor, Codex, Windsurf, Kiro, OpenCode) lemma start # gateway + dashboard on http://localhost:8081 ``` > **Muse** โ€” no setup needed. This repo is already Muse-compatible zero-config: clone and open with `muse` โ€” the skill at `.agents/skills/lemma/SKILL.md` auto-loads and `lemma call` works via `bash`. See [MCP integration](#-mcp-integration). > > **๐Ÿ†• v1.22.0 โ€” Lemma auto-activates in every LLM client.** `npm i -g @nxuss/lemma` registers the skill in your **user** catalog (auto-loads in every `muse` session, any project) and `lemma init` wires each project for Muse, Claude Code, Cursor, Codex, Windsurf, Kiro and OpenCode. Health check: `lemma doctor`. > > **๐Ÿ†• v1.26.0 โ€” a memory without evidence is no longer sold as a verified hit, and the Brain > repairs it on the spot.** `search_memory` now splits its results into three buckets โ€” `fresh` > (tracked + verified, the only ones credited `tokensSaved`/`hits`), `stale`, and `UNTRACKED` > (no files/symbols to re-check: flagged with โš ๏ธ and its remedy, never "from cache"). On the > maintenance side, `brain_upkeep` auto-anchors those evidence-free memories when their body > names real repo files โ€” corpus snapshot first (`auto-anchor`), reversible via > `brain_trash restore-snapshot`; `autoAnchor:false` keeps the old read-only pass. > > **๐Ÿ†• v1.24.0 โ€” the Brain stops crediting what it can't verify.** `smarter_cache` no longer > presents a stale hit as a clean one (`stale:true`/`tokensSaved:0` + why, instead of a silent > guess); `store_memory` derives evidence by default from files/symbols the session already > touched instead of depending on the caller to pass them; every "tokens saved" figure now cites > the `hits` that earned it. See [`CHANGELOG.md`](CHANGELOG.md) for the full list. --- ## โœจ What Lemma actually does - **Shared Semantic Memory ("The Brain")** โ€” a zero-dependency local index (BM25 + Jaccard, no ChromaDB/Ollama required) that persists solutions, fixes, and decisions across every project and every session, with claim- and symbol-level freshness so a stale answer can't hide behind a fresh one. Memories can depend on other memories (`derivedFrom`) and inherit their staleness transitively; `verify_memory` batch-revalidates a set of ids by hash-compare alone, no search round trip; `semanticDiff` tells a comment/formatting-only edit apart from a real one so reformatting a file doesn't falsely invalidate what was learned about it. Write tools (`surgical_ast_insert`, `apply_workspace_patch`, `write_workspace_file`) warn proactively when the code they're about to touch has dependent memories โ€” including a documented failed attempt โ€” instead of only finding out on the next search. Ranking factors in real usage (`hits`), explicit negative feedback (`downvote_memory`), and `cognitive_map` domain tags; a passing `test_oracle` run over an uncommitted diff auto-captures itself; two memories about the same symbol that disagree on outcome are flagged, not silently both suggested. Every hit explains itself (`whyShown` ranking signals + cited `evidence` files/symbols), and every reuse books its savings onto the memory itself โ€” `brain_stats` and `brain_upkeep` name which memories actually pay for the Brain (`totalTokensSaved` alongside the `hits` that earned it, never one without the other). `store_memory` derives `filePaths`/`symbols` by default from whatever the session already read, wrote, or patched when the caller doesn't pass them โ€” flagged as auto-derived in the response, correctable, but no longer opt-in. - **A memory that maintains itself** โ€” `brain_upkeep` revalidates the most-reused memories, surfaces exact duplicates and merge candidates, dead weight, and savings, each finding with its fix. Since v1.26.0 it also **auto-anchors** evidence-free memories whose body names real repo files โ€” snapshot first (`auto-anchor`), then re-anchored to those paths so they become verifiable; `autoAnchor:false` keeps the pass read-only, and everything is reversible via `brain_trash restore-snapshot`. `brain_merge` folds near-duplicate fragments into one canonical entry (fragments survive as evidence-carrying claims). `forget_memory` moves to a trash (`brain_trash`: list/restore/purge) instead of destroying, automatic snapshots roll back every forget/import/clear/merge, and `brain_import dryRun:true` previews a bundle โ€” counts plus opposite-outcome conflicts โ€” before a byte is written. Session onboarding re-checks freshness of the memories it lists, so a day-one answer never starts stale. - **Integrity and encryption at rest** โ€” the corpus carries a sha256 sidecar with `.prev` backup rotation: a half-written or rotted file serves its intact lines, falls back to the backup on total loss, and quarantines (never deletes) the bad bytes, with the incident surfaced in `brain_stats`. `LEMMA_BRAIN_ENCRYPT=1` (or `LEMMA_BRAIN_KEY`) stores the corpus AES-256-GCM encrypted under a local 0600 key; secrets never reach disk at all โ€” scrub-on-store redacts credentials one-way before indexing or persisting. - **Verifiable caching, not marketing numbers** โ€” `state_hash_cache` only hits when the files an answer depends on are byte-identical, and reading a file it already tracks an answer for surfaces that proactively, the same way a Brain memory does. A `smarter_cache` hit on a memory whose evidence changed comes back `stale:true`/`tokensSaved:0` with a warning instead of looking like a clean hit. `token_receipt` gives a real per-session breakdown of how each answer was produced instead of an invented "% saved." - **Privacy Firewall** โ€” API keys, credentials, and PII are scrubbed automatically from every file read and workspace search, before anything leaves your machine. - **Zero-token static intelligence** โ€” dependency graphs, entropy/coupling/risk scores, and an AST symbol index, computed locally with the TypeScript Compiler API. No LLM calls, no tokens. - **Command output distillation** โ€” a failing `npm test`/`tsc` run is parsed by deterministic per-format rules (jest, tsc, eslint) down to the failures that matter; the full output is never lost, just stored and retrievable on demand. - **Surgical, AST-based patching** โ€” `surgical_ast_insert` and `refactor` edit or rename by compiler-verified AST location instead of asking the model to output a full-file rewrite. - **Infrastructure Command Center** โ€” 22 free tools for Jenkins, OKD/OpenShift, and Terraform: discover, connect, deploy, diagnose, and detect drift, all via MCP. - **Scoped tool surface** โ€” of the 109 registered tools, only the ones your project shows evidence of needing are advertised to the model each turn; the rest stay one `lemma_toolbox` call away. See [`CHANGELOG.md`](CHANGELOG.md) for the full, per-version history. --- ## ๐Ÿ’Ž Free vs Pro 59 of the 109 registered tools work with no license; 50 require Pro. Enforced by one allowlist in code (`FREE_TOOLS` in `src/mcp/tools.ts`, including all 22 infrastructure tools), not by narrative. A session without a license doesn't even advertise the Pro tools โ€” they stay registered and discoverable via `lemma_toolbox`. | | Free (59) | Pro (50) | | :--- | :--- | :--- | | **Caching & memory** | `smarter_cache`, `state_hash_cache`, `token_receipt`, `search_memory`, `list_memories`, `store_memory`, `downvote_memory`, `verify_memory`, `token_budget`, `brain_upkeep`, `brain_trash`, `brain_merge` | `get_telepathic_hints`, `query_hybrid_consensus`, `semantic_dedup_guard`, `local_semantic_autofix` | | **Reading & context** | `read_workspace_file`, `scrub_privacy`, `import_tree_context`, `bulk_file_digest`, `auto_context_bundle`, `git_blame_heat`, `type_coverage_report` | `get_ast_hologram`, `smart_file_slice`, `get_symbol_surgical_context`, `diff_only` | | **Writing & workspace** | โ€” | `write_workspace_file`, `apply_workspace_patch`, `multi_file_patch`, `search_workspace`, `run_workspace_command`, `validate_patch_sandbox`, `surgical_ast_insert` | | **Static analysis** | โ€” | `entropy_score`, `coupling_radar`, `pattern_fossil`, `precrime_static`, `dead_export_necromancer`, `depgraph`, `refactor`, `ast_flow_visualizer`, `cognitive_map` | | **Infrastructure** | All 22: `infra_*`, `jenkins_*`, `okd_*`, `terraform_*` | โ€” | | **Automation & PR review** | `conversation_checkpoint`, `test_autofix_interceptor`, `prompt_pattern_cache` | `review_diff`, `review_pr`, `pr_status`, `test_oracle`, `auto_heal`, AutoPilot, Silent Patch Watcher | Get Pro: `lemma activate ` โ†’ [lemma.nxus.studio/upgrade](https://lemma.nxus.studio/upgrade) Full per-tool listing: `lemma_toolbox { "action": "list" }`. --- ## ๐ŸŽš๏ธ Tool profiles Every advertised tool schema is re-sent on **every request** of the session โ€” advertising all 109 costs ~11,600 tokens/turn. Lemma advertises a scoped surface instead: core tools always, situational groups (e.g. infrastructure) only when the repo shows evidence for them. Nothing is removed โ€” everything stays registered and reachable via `lemma_toolbox`. ```jsonc // lemma.config.json { "mcp": { "toolProfile": "full" } } // "auto" (default) | "core" | "full" ``` ```jsonc lemma_toolbox { "action": "list", "query": "terraform drift" } // what exists lemma_toolbox { "action": "schema", "tool": "terraform_drift" } // its inputs lemma_toolbox { "action": "call", "tool": "terraform_drift", "args": {} } ``` `token_budget` reports the profile in use and what the advertised schemas actually cost this session. --- ## ๐Ÿ› ๏ธ CLI reference | Command | Action | | :--- | :--- | | `lemma init` | Bootstraps config and auto-configures MCP for OpenCode, Claude Desktop, Cursor, Windsurf, Kiro, VS Code. | | `lemma start` | Launches proxy, cache engine, and dashboard at `http://localhost:8081`. | | `lemma stop` / `lemma status` / `lemma stats` | Stop, health check, and net token/cost report (reports `NET COST` when a session is underwater). | | `lemma mcp` | Starts the stdin/stdout MCP server for IDE integration. | | `lemma heal` / `lemma autopilot` / `lemma watch` | Diagnose+repair the last crash / toggle autonomous fix-apply / silent patch-only watcher. | | `lemma patches` / `lemma apply ` / `lemma discard ` | List, apply, or discard a pending Silent Patch Watcher fix. | | `lemma activate ` | Activate a Pro license. | | `lemma-checkpoint [projectRoot]` | Derive a session checkpoint from repo state (branch, changed files, commits) with no assistant call. | | `lemma-brain-ingest [projectRoot] [--changelog]` | Feed The Brain from git commits and `CHANGELOG.md`, incrementally. | Wire the standalone bins into hooks so memory doesn't depend on the assistant remembering to call a tool: ```jsonc // ~/.claude/settings.json { "hooks": { "SessionEnd": [{ "hooks": [{ "type": "command", "command": "lemma-checkpoint \"${CLAUDE_PROJECT_DIR:-$PWD}\"" }] }] } } ``` ```bash echo 'lemma-brain-ingest "$(git rev-parse --show-toplevel)" &' >> .git/hooks/post-commit chmod +x .git/hooks/post-commit ``` Customize via `lemma.config.json`: ```json { "system": { "clipboardWatcher": { "disabled": false } }, "mcp": { "allowedCommandPrefixes": ["npm", "git", "tsc", "your-custom-tool"] } } ``` --- ## ๐Ÿ”Œ MCP integration | Client | Setup | | :--- | :--- | | **Muse** (`muse` CLI ยท Muse Spark) | `lemma init` installs the skill into your **user** catalog (`muse skills install --scope user`, auto-loads in every session) + project skill; `npm i -g @nxuss/lemma` also registers it via postinstall. `lemma call` wrapper via `bash` (no MCP native needed). Health check: `lemma doctor`. | | OpenCode | `lemma init` โ€” registers itself in `~/.opencode.json`, zero config. | | Cursor / Windsurf / Kiro / Antigravity | Settings โ†’ MCP โ†’ add server, command `lemma mcp`. | | Claude Desktop | Add to `mcpServers`: `{ "lemma": { "command": "npx", "args": ["-y", "@nxuss/lemma", "mcp"] } }` | | Claude Code / Codex CLI | `lemma init` โ€” auto-configures MCP + sets gateway (`ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` โ†’ `http://localhost:8081`). | Once connected, Lemma auto-injects its TurboMode system prompt on handshake โ€” states the goal (reduce what enters context without ever costing a correct answer) and enforces it: a tool call must save more than its own round-trip, `smarter_cache` hits are disclosed as cached and re-verified before being acted on, `store_memory` only fires after a solution is verified, and compression is always for the model's own context โ€” the user gets the real file. --- ## ๐Ÿ“ก MCP resources | Resource URI | Description | | :--- | :--- | | `lemma://runtime/context` | Live application errors, stack traces, and runtime state. | | `lemma://stats/usage` | Current token savings, cost report, and cache hit metrics. | | `lemma://project/context` | Active project metadata, tech stack, memory count. | | `lemma://project/onboarding` | Dynamic project architecture guide. | | `lemma://multiverse/timeline` | Chronological AST diff timeline of recent snapshots. | --- ## ๐Ÿ”’ Security **Network binding.** Binds only to `127.0.0.1` by default โ€” not network-accessible unless you set `LEMMA_BIND_HOST=0.0.0.0` and enable `AUTH_ENABLED`/`AUTH_REQUIRE_API_KEY`/`AUTH_ALLOWED_ORIGINS`. **Command allowlist.** `run_workspace_command` is deny-by-default, with defaults covering normal JS/TS, Python, Go, Rust, Ruby, JVM, `make`, git/gh, read-only shell utilities, and container/infra CLIs. Extend via `lemma.config.json` โ†’ `mcp.allowedCommandPrefixes`. See [`.env.security.example`](.env.security.example) for every security-related env var. **Brain at rest.** Secrets are redacted one-way before a memory is indexed or persisted (scrub-on-store, same patterns as the traffic firewall โ€” the token map is discarded, there is no unmask step). `LEMMA_BRAIN_ENCRYPT=1` additionally stores the corpus AES-256-GCM encrypted under `/.brain.key` (0600, auto-generated); `LEMMA_BRAIN_KEY` (64 hex chars or base64 of 32 bytes) overrides it for teams sharing one key. A malformed key fails loud at startup; a wrong key flows into the integrity fallback (backup โ†’ quarantine โ†’ fresh start), never an exception, never half a corpus. --- ## ๐Ÿฆœ SDK integrations & proxy mode ```typescript import { LemmaCrewAIProvider } from '@nxuss/lemma/crewai'; const crew = new LemmaCrewAIProvider({ agents: [...] }); ``` Point any OpenAI-compatible tool at `http://localhost:8081/v1` for transparent caching and privacy (Cursor: Settings โ†’ Models โ†’ Override Base URL; VS Code/Continue: `apiBase`). --- MIT ยฉ Nxus Studio | [Upgrade to Lemma Pro](https://lemma.nxus.studio/upgrade)