@nxuss/lemma 1.7.2 → 1.8.1

package/README.md

@@ -1,11 +1,11 @@
-# 🧠 Lemma v1.7.0
+# 🧠 Lemma v1.8.1
 
 [![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-94-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-95-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-267%20passing-00c853?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![Tests](https://img.shields.io/badge/tests-309%20passing-00c853?style=flat-square)](https://github.com/Nxusbets/lemma)
 
 ```text
     __                                
@@ -17,9 +17,9 @@
 
 > **The Intelligent local-first AI Gateway — Privacy, Performance, Static Code Intelligence, and Infrastructure Command Center for the Agentic Era.**
 
-Lemma is a high-performance orchestration layer that sits between your development environment and LLM providers. It transforms the way you build with AI by providing **Shared Semantic Memory**, **Autonomous Cost Optimization**, **Privacy Guardrails**, **22 Infrastructure Management Tools**, and a suite of **94 MCP tools** — including zero-token static code intelligence that runs entirely on your machine with no LLM calls required.
+Lemma is a high-performance orchestration layer that sits between your development environment and LLM providers. It transforms the way you build with AI by providing **Shared Semantic Memory**, **Autonomous Cost Optimization**, **Privacy Guardrails**, **22 Infrastructure Management Tools**, and a suite of **95 MCP tools** — including zero-token static code intelligence that runs entirely on your machine with no LLM calls required.
 
-Since v1.7.0 those 94 tools are all registered, but only the ones your project can actually use
+Since v1.7.0 those 95 tools are all registered, but only the ones your project can actually use
 are advertised to the model each turn. The rest stay one `lemma_toolbox` call away. See
 [Tool profiles](#-tool-profiles).
 
@@ -27,7 +27,61 @@ are advertised to the model each turn. The rest stay one `lemma_toolbox` call aw
 
 ## 📋 Changelog
 
-### v1.7.0 — The cost of being connected *(NEW)*
+### v1.8.1 — Two correctness fixes: secret scrubbing and patch data loss *(NEW)*
+
+An audit of the tools with no test coverage turned up two bugs where the tool looked done but
+silently produced wrong output.
+
+- **`apply_workspace_patch` could corrupt a line.** The exact-match strategy computed
+  `startLine`/`endLine` from a raw substring `indexOf`, but the handler always spliced by whole
+  line. A search block that was a *fragment* of a line (not the entire line) collapsed
+  `startLine === endLine`, and the splice replaced the entire line with just the replacement —
+  discarding everything else on it. Exact matches now splice by character offset;
+  whitespace-normalized/indent-anchored/fuzzy matches (already full-line windows) are unaffected.
+- **The privacy scrubber only recognized 3 generic patterns.** Default patterns covered
+  `API_KEY`/`EMAIL`/`Bearer ...` shapes only — vendor-specific secrets (Stripe, AWS, GitHub,
+  Google, Slack, JWTs, PEM private-key blocks) and custom-named secrets (e.g. a project's own
+  `_SALT` or `_WEBHOOK_SECRET` env var) passed through unmasked. Also, a project's custom
+  `lemma.config.json` patterns silently *replaced* the defaults instead of adding to them, so
+  defining one narrow pattern dropped coverage for everything else. Added vendor-specific
+  patterns plus a generic `ENV_SECRET` catch-all keyed on variable-name conventions, and custom
+  patterns now augment the defaults by default (`replaceDefaults: true` opts into full override).
+
+### v1.8.0 — The Brain learns from project history, not just what it's told *(NEW)*
+
+Every memory in The Brain used to depend on the assistant remembering to call `store_memory`. If
+nobody called it, the Brain knew nothing about work that already happened.
+
+| Change | What it does | Why it matters |
+| :--- | :--- | :--- |
+| **`lemma-brain-ingest`** *(new CLI)* | Feeds The Brain from git commits and `CHANGELOG.md` — no assistant call needed. Incremental via a marker file, safe to wire to `post-commit`. | The Brain stops depending on the model remembering to save anything. |
+| **Checkpoints now feed The Brain** | `saveCheckpoint()` indexes any checkpoint with real content into the same Brain `search_memory` reads. | Decisions and bugs recorded in a checkpoint used to be invisible to search. |
+| **`get_project_history`** *(new tool)* | Merges recent commits, checkpoints, and Brain memories for the current project into one call. | Answers "what have we done here" without three separate lookups. |
+| **Outcome tagging** | `store_memory` accepts `outcome: 'failed'`; search surfaces it as a warning, not a suggestion. | A dead end is now as memorable as a fix. |
+| **Symbol-level freshness** | `store_memory` accepts `symbols: [{filePath, symbolName}]` — freshness is judged by that function's own source, not the whole file. | An unrelated edit elsewhere in the file no longer stales the memory out. |
+
+**PR review memory was silently going nowhere.** `BrainBridge` talked to the proxy's
+`/api/search`/`/api/memory/store`, both backed by ChromaDB + a local Ollama server on `:11434` —
+the exact stack TheBrainV2 replaced in 1.0.0. Whenever Ollama wasn't running (the common case
+now), every call failed inside a `try/catch` and returned empty. It now reads/writes `TheBrainV2`
+directly, so PR review and interactive coding share one memory instead of two disconnected ones.
+
+**Two projects could quietly share — or split — memories.** `deriveProjectId` hashed the
+project path without resolving symlinks; on macOS `process.cwd()` and an `os.tmpdir()`-built path
+can report different strings for the same directory, hashing to two different project scopes. It
+now resolves via `fs.realpathSync` first.
+
+**Spanish text was mangled before it reached the index.** `tokenize()` used `\w` to strip
+punctuation, which doesn't match accented letters — "Cómo" became "mo", "diseño" became "dise",
+and the same word typed without its accent tokenized completely differently. `tokenize()` now
+normalizes diacritics first, and gained an additive English/Spanish stemmer and Spanish stopwords.
+
+**`token_budget` reported a multiplier no ledger backed.** It fetched a proxy route that doesn't
+exist, silently fell back to an uncosted estimate, and reported a bigger number than the
+session's own auditable ledger would support. It now reads the real `SavingsLedger` net position
+(`/api/savings-breakdown`) or says plainly there's nothing to report if the proxy isn't running.
+
+### v1.7.0 — The cost of being connected
 
 Every tool schema Lemma advertises goes into the model's system prompt and is **re-sent on every
 request of the session** — including schemas for tools the project can never use. On this repo that
@@ -288,7 +342,7 @@ Or use environment variables: `JENKINS_URL`, `JENKINS_USERNAME`, `JENKINS_API_TO
 ## 🎚️ Tool profiles
 
 Every tool schema an MCP server advertises is injected into the model's system prompt and re-sent
-on **every request** of the session. Advertising all 94 tools costs ~11,600 tokens per turn — much
+on **every request** of the session. Advertising all 95 tools costs ~11,600 tokens per turn — much
 of it schemas for tools a given project can never use.
 
 Lemma advertises a scoped surface instead. Nothing is removed: every tool stays registered and
@@ -349,14 +403,57 @@ the richer record when one exists.
 
 ---
 
+## 🧠 Feeding The Brain from project history
+
+`store_memory` also depends on the assistant remembering to call it. `lemma-brain-ingest` pulls
+memories from sources that already exist and don't need an assistant in the loop:
+
+```bash
+lemma-brain-ingest [projectRoot] [--max N] [--changelog] [--no-commits]
+```
+
+- Every git commit (message + files touched) becomes one Brain entry, so `search_memory` and
+  `get_telepathic_hints` can recall *why* a change happened, not just what the code looks like now.
+- `--changelog` also ingests `CHANGELOG.md` (falls back to `docs/CHANGELOG.md`) — one entry per release, parsed
+  directly, no LLM involved.
+
+A marker file under `<project>/.lemma/session/` tracks the last commit and changelog version
+ingested, so this is safe to run after every commit and safe to run by hand for a one-time
+backfill of existing history — both take the same incremental path and never double-store.
+Wire it to a post-commit hook to keep it current automatically:
+
+```bash
+echo 'lemma-brain-ingest "$(git rev-parse --show-toplevel)" &' >> .git/hooks/post-commit
+chmod +x .git/hooks/post-commit
+```
+
+---
+
 ## 💎 Free vs Pro
 
-### 🆓 Free (33 Tools)
+Of the 95 registered tools, 46 work with no license and 49 require Pro. This split is enforced by
+one allowlist in code (`FREE_TOOLS` in `src/mcp/tools.ts`), not by narrative — if a tool isn't in
+that list, it's Pro, regardless of what a description elsewhere implies.
+
+### 🆓 Free (46 Tools)
 
 These tools work **without a Pro license**. Activate them with just `lemma init`:
 
 | Tool | What It Does |
 | :--- | :--- |
+| `smarter_cache` | Semantic cache lookup before reasoning from scratch |
+| `state_hash_cache` | Reasoning cache keyed to file content hashes — exact invalidation |
+| `token_receipt` | Auditable per-session ledger of how each answer was produced |
+| `search_memory` | Semantic search across The Brain, all projects |
+| `store_memory` | Persist verified solutions/fixes/decisions into The Brain |
+| `get_project_history` | Git log + checkpoints + Brain memories in one call |
+| `token_budget` | Session token/cost dashboard, including Lemma's own overhead |
+| `squeeze_prompt` | Compress code blocks before they enter your own context |
+| `turbosqueeze` | Extreme internal-context compression (never shown to the user) |
+| `read_workspace_file` | Read a file with auto-compression and privacy scrubbing |
+| `scrub_privacy` | Mask PII, API keys, and secrets from any text block |
+| `summarize_long_text` | Summarize via local Ollama, falls back to truncation |
+| `lemma_toolbox` | List, inspect, and call tools whose schemas were withheld |
 | `file_fingerprint` | File hash cache — avoid re-reads |
 | `git_blame_heat` | Git blame + risk scoring |
 | `type_coverage_report` | TypeScript type safety score |
@@ -391,25 +488,27 @@ These tools work **without a Pro license**. Activate them with just `lemma init`
 | `terraform_state_list` | List Terraform state resources |
 | `terraform_drift` | Detect Terraform drift |
 
-### 💎 Pro (51 Tools)
+### 💎 Pro (49 Tools)
 
 All remaining tools require a Pro license. Activate with `lemma activate <key>` → [Get Pro](https://lemma.nxus.studio/upgrade)
 
 | Category | Tools |
 | :--- | :--- |
-| **AI Proxy** | OpenAI/Anthropic/Gemini proxy, exact-match cache, context squeezer, complexity router |
-| **Privacy** | Privacy firewall (semantic scrubber), PII masking |
-| **The Brain** | Semantic memory, telepathic hints, hybrid consensus, smarter cache, dedup guard |
-| **Zero-Token Static** | entropy_score, coupling_radar, pattern_fossil, git_heatmap_risk, precrime_static, dead_export_necromancer |
-| **Architecture** | depgraph, refactor, ast_flow_visualizer, imports_skeleton_resolver |
-| **Code Intelligence** | get_ast_hologram, validate_patch_sandbox, surgical_ast_insert, get_symbol_surgical_context |
-| **Workspace** | read/write/create files, apply patches, search, list dirs, run commands |
-| **Optimization** | turbosqueeze, squeeze_prompt, wormhole_squeeze, compress_context, token_budget |
-| **PR Review** | review_diff, review_pr, pr_status, generate_pr_workflow |
-| **Session** | test_oracle, schema_extract, changelog_auto, env_snapshot, migration_tracer |
-| **Automation** | AutoPilot, Auto-Heal, Silent Patch Watcher |
-
-> **The MCP server is Pro.** All 51 Pro tools — The Brain, PreCrime, AST Hologram, `depgraph`, `refactor`, and every optimization tool — require a Pro license. The 33 Free tools listed above (including all 22 Infrastructure tools) are accessible without activation.
+| **AI Proxy** | OpenAI/Anthropic/Gemini proxy, exact-match cache, complexity router |
+| **The Brain (advanced)** | `get_telepathic_hints`, `query_hybrid_consensus`, `semantic_dedup_guard`, `local_semantic_autofix` — basic search/store/smarter_cache are Free |
+| **Zero-Token Static** | `entropy_score`, `coupling_radar`, `pattern_fossil`, `git_heatmap_risk`, `precrime_static`, `dead_export_necromancer` |
+| **Architecture** | `depgraph`, `refactor`, `ast_flow_visualizer`, `imports_skeleton_resolver`, `cognitive_map`, `file_intent_index` |
+| **Code Intelligence** | `get_ast_hologram`, `validate_patch_sandbox`, `surgical_ast_insert`, `get_symbol_surgical_context`, `smart_file_slice`, `diff_only` |
+| **Workspace writes** | `write_workspace_file`, `create_workspace_file`, `apply_workspace_patch`, `multi_file_patch`, `search_workspace`, `list_workspace_dir`, `run_workspace_command`, `output_region` |
+| **Optimization (advanced)** | `wormhole_squeeze`, `compress_context`, `prune_conversation_history` — `turbosqueeze`, `squeeze_prompt`, `token_budget` are Free |
+| **PR Review** | `review_diff`, `review_pr`, `pr_status`, `generate_pr_workflow` |
+| **Session & Automation** | `test_oracle`, `schema_extract`, `changelog_auto`, `env_snapshot`, `migration_tracer`, `spec_to_stub`, `batch_tool_calls`, `get_routing_advice`, `get_project_onboarding`, `auto_heal`, `semantic_grep` |
+| **Automation (background)** | AutoPilot, Auto-Heal, Silent Patch Watcher |
+
+> **The MCP server itself is Pro.** All 49 Pro tools — the advanced Brain layer, PreCrime, AST
+> Hologram, `depgraph`, `refactor`, every workspace-write tool, and every PR review tool — require a
+> Pro license. The 46 Free tools above (including all 22 Infrastructure tools and `read_workspace_file`
+> with its automatic privacy scrubbing) are accessible without activation.
 
 ---
 
@@ -626,6 +725,8 @@ lemma start
 | `lemma apply <id>` | Apply a pending fix patch. |
 | `lemma discard <id>` | Discard a pending fix patch. |
 | `lemma activate <key>` | Activate Pro license for full MCP access. |
+| `lemma-checkpoint [projectRoot]` | Standalone bin: derive a session checkpoint from repo state (branch, changed files, recent commits) without an assistant call. See [Session checkpoints](#-session-checkpoints). |
+| `lemma-brain-ingest [projectRoot]` | Standalone bin: feed The Brain from git commits and `CHANGELOG.md`, incrementally. See [Feeding The Brain from project history](#-feeding-the-brain-from-project-history). |
 
 ### Customizing via `lemma.config.json`
 
@@ -665,157 +766,32 @@ Just run `lemma init`. Lemma automatically registers its MCP server in your `~/.
 }
 ```
 
-Once connected, your IDE gains access to **62 MCP tools** — 11 free + 51 Pro. Lemma auto-injects the TurboMode system prompt on handshake.
-
----
-
-## 🛠️ MCP Tools Reference (v1.1.0 — 62 Tools)
-
-### 🆓 Free Tools (11)
-
-> These tools work without a Pro license. All are zero-dependency and run locally.
-
-| Tool | Category | Description |
-| :--- | :--- | :--- |
-| `file_fingerprint` | Smart Read | SHA256 hash cache. Returns 'unchanged' when hash matches, avoiding re-reads. |
-| `git_blame_heat` | Analysis | Git blame + risk scoring per line. Identifies hotspots and high-risk authors. |
-| `type_coverage_report` | Analysis | TypeScript type safety score via AST. Reports typed vs untyped, `any` count. |
-| `import_tree_context` | Architecture | Bidirectional import graph with reverse dependencies. |
-| `read_token_budgeted` | Smart Read | Read file with hard token limit. Returns only relevant sections. |
-| `bulk_file_digest` | Smart Read | Read N files in one call. Returns compressed digest. |
-| `auto_context_bundle` | Smart Read | One-call bundle: content + imports + types + Brain hints. |
-| `repeat_guard` | Optimization | Detects duplicate outputs using Jaccard similarity. |
-| `conversation_checkpoint` | Session | Save/load session state to prevent re-explaining context. |
-| `test_autofix_interceptor` | Automation | Run tests + Brain search for matching fixes. |
-| `prompt_pattern_cache` | Optimization | Find/store optimized prompt templates. |
-
-### 🗂️ Workspace Tools
-
-| Tool | Description |
-| :--- | :--- |
-| `read_workspace_file` | Read a file with automatic token compression and privacy scrubbing. |
-| `write_workspace_file` | Write content to a file, creating parent directories as needed. |
-| `create_workspace_file` | Create a new file (fails if exists). Returns minimal ACK. |
-| `apply_workspace_patch` | Smart search-and-replace patch — safe against duplicate matches. |
-| `multi_file_patch` | Apply patches to multiple files in a single call. |
-| `list_workspace_dir` | Recursively list the project structure up to a configurable depth. |
-| `search_workspace` | Fast text search (grep) across all project files. |
-| `semantic_grep` | Natural language concept search using BM25. |
-| `run_workspace_command` | Execute bash commands in the workspace root. Secured by allowlist. Distills long jest/vitest/tsc/eslint output down to the failures and their locations; full output kept retrievable. |
-| `output_region` | Retrieve any part of a stored command output verbatim (whole thing, one failing test, or a line range). |
-| `file_intent_index` | Group files by domain intent (auth, routing, config). |
-
-### 🔬 Code Intelligence Tools
-
-| Tool | Description |
-| :--- | :--- |
-| `get_ast_hologram` | Holographic AST Map of all exported symbols. 90% token savings. |
-| `validate_patch_sandbox` | Pre-flight validator: runs tsc + syntax check before applying. |
-| `diff_only` | Compact line-by-line diff between known states. Session-scoped. |
-| `surgical_ast_insert` | Insert code at AST anchor point. 95% output token savings. |
-| `get_symbol_surgical_context` | Extract symbol + dependency signatures only. 90% savings. |
-| `smart_file_slice` | Read only relevant lines around a query. 85% savings. |
-| `schema_extract` | Extract interfaces/types/schemas via AST. 80% savings. |
-| `spec_to_stub` | Generate mock stubs from TypeScript interfaces. |
-| `ast_flow_visualizer` | Mermaid flowchart from function control flow. |
-| `imports_skeleton_resolver` | Import signature mapper for quick reference. |
-
-### 🧠 Brain & Memory Tools
-
-| Tool | Description |
-| :--- | :--- |
-| `search_memory` | Semantic search across The Brain from all projects globally. |
-| `store_memory` | Persist solutions, fixes, decisions into The Brain. |
-| `query_hybrid_consensus` | Hybrid cache: 80% threshold → instant answer, 0 cloud tokens. |
-| `get_telepathic_hints` | Proactive hints from The Brain based on active file. |
-| `smarter_cache` | Predictive cache at 75% threshold before any reasoning. |
-| `semantic_dedup_guard` | Brain dedup firewall. Rejects ≥92% similar entries. |
-| `local_semantic_autofix` | Offline self-healing from Brain error index. |
-
-### ⚙️ Optimization & Privacy Tools
-
-| Tool | Description |
-| :--- | :--- |
-| `scrub_privacy` | Mask PII, API keys, secrets from any text block. |
-| `squeeze_prompt` | Compress code blocks. Up to 80% token reduction. |
-| `turbosqueeze` | Extreme compression: strips comments, imports, whitespace. |
-| `wormhole_squeeze` | Reversible unicode compression. 60-70% reduction. |
-| `compress_context` | Summarize old conversation turns. Keeps last N intact. |
-| `prune_conversation_history` | Intelligently decimate history preserving critical context. |
-| `summarize_long_text` | Summarize via Ollama. Falls back to truncation. |
-| `token_budget` | Dashboard: multiplier, savings, strategies, recommendations. |
-| `get_routing_advice` | Optimal model recommendation from Complexity Router. |
-| `get_project_onboarding` | One-shot architectural mental model. |
-| `auto_heal` | Auto-diagnose and repair crashes from live context. |
-| `batch_tool_calls` | Execute multiple tools in parallel via Promise.all. |
-
-### 🔮 Zero-Token Static Intelligence Tools
-
-> All tools in this section use **zero LLM tokens**. Pure local computation.
-
-| Tool | Description |
-| :--- | :--- |
-| `entropy_score` | Mathematical chaos score (0-100) per file. |
-| `coupling_radar` | Dependency graph: circular imports, god modules, dead islands. |
-| `pattern_fossil` | Zombie code detector: var vs const, callbacks vs async/await. |
-| `git_heatmap_risk` | Git churn analysis + co-edit pairs. |
-| `precrime_static` | Composite risk predictor combining entropy + coupling + git. |
-| `dead_export_necromancer` | Dead code auditor: exported but never imported. |
-| `git_blame_heat` | Git blame + per-line risk scoring. |
-| `type_coverage_report` | TypeScript type safety score. |
-| `import_tree_context` | Bidirectional import graph. |
-
-### 🏗️ Architecture & Refactoring Tools
-
-| Tool | Description |
-| :--- | :--- |
-| `depgraph` | Real-time dependency graph with depth, format, circular detection. |
-| `refactor` | Declarative codemod: rename symbols or move files. |
-| `cognitive_map` | Auto-updating knowledge graph of domains and patterns. |
-
-### 🔍 PR Review Agent Tools
-
-| Tool | Description |
-| :--- | :--- |
-| `review_diff` | Analyze raw diff for bugs, security, best practices. |
-| `review_pr` | Full PR review against GitHub, Azure DevOps, GitLab. |
-| `pr_status` | Query last review status for a PR. |
-| `generate_pr_workflow` | Generate CI/CD workflow YAML for PR reviews. |
-
-### 🧪 Testing & Quality Tools
-
-| Tool | Description |
-| :--- | :--- |
-| `test_oracle` | Run tests, return only failures with compressed traces. |
-| `test_autofix_interceptor` | Run tests + Brain search for matching fixes. |
-| `changelog_auto` | Conventional commit changelog from git history. |
-| `env_snapshot` | Node/npm versions, deps, .env keys (values hidden). |
-| `migration_tracer` | Prisma migration schema diff analysis. |
-
-### 📋 Session & Automation Tools
-
-| Tool | Description |
-| :--- | :--- |
-| `conversation_checkpoint` | Save/load session state to `.lemma/session/`. |
-| `prompt_pattern_cache` | Find/store optimized prompt templates. |
-| `review_pr` | Full PR review with auto-approve option. |
+Once connected, your IDE gains access to all **95 MCP tools** (46 Free + 49 Pro — see
+[Free vs Pro](#-free-vs-pro) for the full, current split) and Lemma auto-injects the TurboMode
+system prompt on handshake. By default only the tools your project shows evidence of needing are
+*advertised* each turn — see [Tool profiles](#-tool-profiles) — but every tool is registered and
+reachable via `lemma_toolbox` regardless of profile.
 
 ### ⚡ TurboMode Auto-Injection
 
-When connected via `lemma mcp`, Lemma auto-injects 12 rules into the agent's system prompt on handshake:
-
-1. `turbosqueeze` before writing large code blocks
-2. `smarter_cache` before any reasoning
-3. `store_memory` after every resolved solution
-4. `get_ast_hologram` before reading files
-5. `batch_tool_calls` for parallel operations
-6. `semantic_dedup_guard` before every `store_memory`
-7. No fluff, no chit-chat — maximum density
-8. `auto_context_bundle` or `bulk_file_digest` for multi-file ops
-9. `repeat_guard` before long outputs
-10. `conversation_checkpoint` to restore session context
-11. `test_autofix_interceptor` when tests fail
-12. `prompt_pattern_cache` for repetitive prompts
+When connected via `lemma mcp`, Lemma auto-injects its system prompt on handshake. The real,
+current prompt (`LEMMA_TURBOMODE_PROMPT` in `src/mcp/prompts.ts`) states the goal — reduce what
+enters context without ever costing a correct answer — and enforces it with rules including:
+
+- A tool call costs tokens too: expect a call to save more than its own round-trip, or skip it.
+- `lemma_toolbox` reaches every tool whose schema was withheld from this session — check it
+  before saying a capability is missing.
+- Compression (`turbosqueeze`, `wormhole_squeeze`, `squeeze_prompt`) is for the model's own
+  context only; the user always gets the real, uncompressed file.
+- `smarter_cache` hits must be disclosed as cached, never presented as freshly reasoned, and
+  re-verified before acting on them.
+- `state_hash_cache` (exact file-hash invalidation) is preferred over `smarter_cache` (semantic
+  similarity) whenever the answer depends on specific files.
+- `store_memory` only after a solution is actually verified — an unverified fix stored here
+  becomes a false cache hit later.
+- `get_routing_advice` before assuming a mechanical task needs the biggest available model.
+- `surgical_ast_insert` by default for adding to an existing file, instead of rewriting it whole.
+- `token_receipt` for "how much did we save," never an invented estimate.
 
 ---
 
@@ -860,15 +836,6 @@ See [`.env.security.example`](.env.security.example) for all security-related en
 
 ## 🦜 SDK Integrations
 
-### LangChain
-```typescript
-import { LemmaLangChainProvider } from '@nxuss/lemma/langchain';
-
-const model = new LemmaLangChainProvider({
-  apiKey: process.env.OPENAI_API_KEY,
-});
-```
-
 ### CrewAI
 ```typescript
 import { LemmaCrewAIProvider } from '@nxuss/lemma/crewai';

package/bin/brain-ingest.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Feeds The Brain from sources the model never has to remember to store manually.
+ *
+ * Meant to be wired to a git post-commit hook so every commit becomes a searchable memory
+ * without depending on the assistant calling `store_memory`:
+ *
+ *   echo 'lemma-brain-ingest "$(git rev-parse --show-toplevel)" &' >> .git/hooks/post-commit
+ *
+ * With no flags it's an incremental catch-up: a marker file under .lemma/session/ tracks the
+ * last commit ingested, so running this after every commit or by hand both take the same path
+ * and never double-store. `--max N` only matters the first time there is no marker yet.
+ *
+ * Usage: lemma-brain-ingest [projectRoot] [--max N] [--changelog] [--no-commits]
+ */
+
+const path = require('path');
+
+function main() {
+  const args = process.argv.slice(2);
+  const maxIndex = args.indexOf('--max');
+  const maxCommits = maxIndex >= 0 ? parseInt(args[maxIndex + 1], 10) : undefined;
+  const includeChangelog = args.includes('--changelog');
+  const includeCommits = !args.includes('--no-commits');
+  const positional = args.filter((a, i) => !a.startsWith('--') && i !== maxIndex + 1);
+  const projectRoot = path.resolve(positional[0] || process.cwd());
+
+  const distPath = path.join(__dirname, '..', 'dist', 'cjs', 'subconscious', 'GitIngest.js');
+  let ingestRecentCommits, ingestChangelog;
+  try {
+    ({ ingestRecentCommits, ingestChangelog } = require(distPath));
+  } catch {
+    console.error('[lemma-brain-ingest] Build not found. Run "npm run build" first.');
+    return;
+  }
+
+  if (includeCommits) {
+    const res = ingestRecentCommits(projectRoot, { maxCommits });
+    console.error(`[lemma-brain-ingest] commits: ${res.ingested} stored, ${res.skipped} skipped (up to ${res.lastSha ? res.lastSha.substring(0, 12) : 'none'})`);
+  }
+
+  if (includeChangelog) {
+    const res = ingestChangelog(projectRoot);
+    console.error(`[lemma-brain-ingest] changelog: ${res.ingested} stored, ${res.skipped} skipped (${res.versionsSeen} version(s) seen)`);
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  // A hook that fails must never be the reason a commit or session goes bad.
+  console.error('[lemma-brain-ingest] Skipped:', err && err.message);
+}
+process.exit(0);

package/dist/cjs/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAiiCnE,oFAAoF;AACpF,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,IAAI;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAQA;AAoHD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqCD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,IAAI,CAwEN"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAwjCnE,oFAAoF;AACpF,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,IAAI;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAQA;AAqHD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqCD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,IAAI,CAwEN"}