@nxuss/lemma 1.27.1 → 1.29.0

package/README.md

@@ -2,10 +2,10 @@
 
 [![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)
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-110-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)
+[![Tests](https://img.shields.io/badge/tests-964%20passing-00c853?style=flat-square)](https://github.com/Nxusbets/lemma)
 
 ```text
     __
@@ -35,6 +35,25 @@ lemma start     # gateway + dashboard on http://localhost:8081
 >
 > **🆕 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.29.0 — the dashboard shows what the Brain knows.** `lemma start` now opens with a
+> 🧠 Brain panel: how many files of your codebase it carries evidence about, how many times a
+> memory reached an agent's context, growth this week, how much of it is verifiable against the
+> code, where memories come from (manual, red → green fixes, tests, commits, team), and the most
+> recalled ones. Token savings stay as a footnote — the Brain's value is agents not re-discovering
+> context. Same numbers in `brain_stats` and at `GET /api/brain/stats`.
+>
+> **🆕 v1.28.0 — the Brain goes team-wide through git, and fills itself.** `brain_team push`
+> writes your verified memories into the repo (`.lemma-brain/memories/`, one reviewable JSON file
+> each, paths relative to the repo root); `brain_team pull` — automatic on merge/checkout once
+> `lemma init` installs the hooks — imports a teammate's memories rebased onto *your* checkout. A
+> memory about a file that is byte-identical on your machine arrives **fresh**; one whose file has
+> moved on arrives **stale**, never silently trusted. And memories no longer depend on the model
+> remembering `store_memory`: a test/build/lint command that goes **red → green** is captured as
+> `fix: <the error>` + the files and diff that fixed it — searchable by the exact error message next
+> time — whether it ran through `run_workspace_command` or the agent's own shell (Claude Code
+> `PostToolUse` hook). Commits become memories anchored to their own blobs. Also fixes
+> `lemma-brain-ingest` silently dropping everything it ingested.
+>
 > **🆕 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`
@@ -64,7 +83,7 @@ lemma start     # gateway + dashboard on http://localhost:8081
   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
+  tags; a command that goes red → green auto-captures the fix (see below); 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
@@ -72,6 +91,27 @@ lemma start     # gateway + dashboard on http://localhost:8081
   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 team Brain, shared through git** — `brain_team push` writes this project's fresh, tracked
+  memories to `.lemma-brain/memories/<id>.json`: one sorted-key JSON file per memory, so two people
+  sharing at once never conflict, every shared memory goes through code review, and deleting one is
+  a `git rm`. Evidence is stored relative to the repo root and rebased onto each clone on `pull`,
+  hashes untouched — a teammate's memory is verified against *your* files, fresh only if they are
+  byte-identical. Never shared: conversation checkpoints, commit memories (each clone derives its
+  own), untracked or stale memories, evidence outside the repo, or anything derived from a memory
+  that isn't shared. A pulled path that is absolute or escapes the repo is rejected; a memory a
+  teammate deletes leaves your clone into `brain_trash` (restorable), and one you wrote yourself is
+  never removed. Pushing is always explicit; pulling is a no-op when nothing changed, so it runs on
+  every merge/checkout. `brain_team status` shows both sides; `dryRun:true` previews either.
+- **Memories that write themselves** — a verdict command (jest, vitest, pytest, tsc, eslint, `go
+  test`, `cargo test`, `npm test`/`build`/`lint`, …) that fails and later passes stores
+  `fix: <headline error>` with the failure signature, the files whose content changed between the
+  two runs, and their diff — tracked against those files, tagged `confirmed`, source `auto-fix`.
+  A pass with nothing changed since the failure is treated as flaky and stores nothing; a "fix" over
+  15 files is a refactor and stores nothing. It sees `run_workspace_command`, `test_oracle`, and — via
+  `lemma-brain-ingest --hook-result` — the agent's own Bash tool. Commits are ingested with each
+  touched file anchored to its blob *in that commit* (`git show sha:path`), not to the working copy.
+  `lemma init` installs the `post-commit`, `post-merge` and `post-checkout` hooks that drive this
+  (appended to existing hooks, idempotent, never touches a versioned `core.hooksPath` like husky).
 - **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
@@ -106,7 +146,7 @@ lemma start     # gateway + dashboard on http://localhost:8081
   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
+- **Scoped tool surface** — of the 110 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.
@@ -115,14 +155,14 @@ 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
+60 of the 110 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) |
+| | Free (60) | 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` |
+| **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`, `brain_team` | `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` |
@@ -137,8 +177,8 @@ 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
+Every advertised tool schema is re-sent on **every request** of the session — advertising all 110
+costs ~11,900 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`.
 
@@ -161,15 +201,16 @@ lemma_toolbox { "action": "call",   "tool":  "terraform_drift", "args": {} }
 
 | 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 init` | Bootstraps config, auto-configures MCP for OpenCode, Claude Desktop, Cursor, Windsurf, Kiro, VS Code, and installs the git hooks that feed the Brain (`--no-hooks` to skip). |
+| `lemma start` | Launches proxy, cache engine, and dashboard at `http://localhost:8081` (gateway savings + Brain knowledge panel). |
 | `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 <id>` / `lemma discard <id>` | List, apply, or discard a pending Silent Patch Watcher fix. |
 | `lemma activate <key>` | 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. |
+| `lemma-brain-ingest [projectRoot] [--changelog] [--team-pull]` | Feed The Brain from git commits and `CHANGELOG.md`, incrementally; `--team-pull` imports the repo's `.lemma-brain/`. |
+| `lemma-brain-ingest --hook-result` | Read a host `PostToolUse` payload on stdin and capture red → green fixes from the agent's own shell. |
 
 Wire the standalone bins into hooks so memory doesn't depend on the assistant remembering to call a tool:
 
@@ -179,11 +220,16 @@ Wire the standalone bins into hooks so memory doesn't depend on the assistant re
   "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
+```jsonc
+// .claude/settings.json — red → green fixes from Claude Code's own Bash tool become memories
+{ "hooks": { "PostToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command",
+  "command": "lemma-brain-ingest --hook-result" }] }] } }
 ```
 
+The git side needs nothing by hand: `lemma init` installs `post-commit` (commit → memory) and
+`post-merge`/`post-checkout` (pull the team's `.lemma-brain/`). With a versioned hooks dir
+(`core.hooksPath`, e.g. husky) it prints the lines to add instead of editing team files.
+
 Customize via `lemma.config.json`:
 
 ```json

package/bin/brain-ingest.js

@@ -13,18 +13,54 @@
  * 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]
+ * Usage: lemma-brain-ingest [projectRoot] [--max N] [--changelog] [--no-commits] [--team-pull]
+ *        lemma-brain-ingest --hook-result < payload.json
+ *
+ * --team-pull   Import the repo's shared memories from .lemma-brain/ (post-merge/post-checkout).
+ * --hook-result Read a host PostToolUse hook payload on stdin (Claude Code's Bash tool shape) and
+ *               feed it to FixCapture, so a test that goes red → green through the agent's own
+ *               shell becomes a memory too. Wire it in .claude/settings.json:
+ *                 "hooks": { "PostToolUse": [{ "matcher": "Bash",
+ *                   "hooks": [{ "type": "command", "command": "lemma-brain-ingest --hook-result" }] }] }
  */
 
 const path = require('path');
 
+function readStdin() {
+  try {
+    return require('fs').readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function hookResult() {
+  const distPath = path.join(__dirname, '..', 'dist', 'cjs', 'utils', 'FixCapture.js');
+  let recordHookPayload;
+  try {
+    ({ recordHookPayload } = require(distPath));
+  } catch {
+    return; // no build — a hook must stay silent and harmless
+  }
+  let payload;
+  try {
+    payload = JSON.parse(readStdin());
+  } catch {
+    return;
+  }
+  const res = recordHookPayload(payload, payload && payload.cwd);
+  if (res && res.captured) console.error(res.note.trim());
+}
+
 function main() {
   const args = process.argv.slice(2);
+  if (args.includes('--hook-result')) return hookResult();
   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 teamPull = args.includes('--team-pull');
+  const positional = args.filter((a, i) => !a.startsWith("--") && (maxIndex < 0 || i !== maxIndex + 1));
   const projectRoot = path.resolve(positional[0] || process.cwd());
 
   const distPath = path.join(__dirname, '..', 'dist', 'cjs', 'subconscious', 'GitIngest.js');
@@ -41,16 +77,42 @@ function main() {
     console.error(`[lemma-brain-ingest] commits: ${res.ingested} stored, ${res.skipped} skipped (up to ${res.lastSha ? res.lastSha.substring(0, 12) : 'none'})`);
   }
 
+  if (teamPull) {
+    try {
+      const { pullTeamBrain } = require(path.join(__dirname, '..', 'dist', 'cjs', 'subconscious', 'TeamBrain.js'));
+      const res = pullTeamBrain(projectRoot);
+      console.error(`[lemma-brain-ingest] team: ${res.message}`);
+    } catch (err) {
+      console.error('[lemma-brain-ingest] team pull skipped:', err && err.message);
+    }
+  }
+
   if (includeChangelog) {
     const res = ingestChangelog(projectRoot);
     console.error(`[lemma-brain-ingest] changelog: ${res.ingested} stored, ${res.skipped} skipped (${res.versionsSeen} version(s) seen)`);
   }
 }
 
+/**
+ * The Brain debounces its writes by 500ms (right for a long-lived server), and process.exit()
+ * below drops pending timers — so without an explicit flush every memory this script stored was
+ * lost the moment it exited. Only flush when the Brain was actually loaded.
+ */
+function flushBrain() {
+  try {
+    const modPath = require.resolve(path.join(__dirname, '..', 'dist', 'cjs', 'subconscious', 'TheBrainV2.js'));
+    if (!require.cache[modPath]) return;
+    require(modPath).getBrain().flushSync();
+  } catch (err) {
+    console.error('[lemma-brain-ingest] flush failed:', err && err.message);
+  }
+}
+
 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);
 }
+flushBrain();
 process.exit(0);