@nxuss/lemma 1.33.0 → 1.35.0

package/README.md

@@ -35,6 +35,19 @@ 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.35.0 — recall *before* the answer, and memories that notice when the world moved.** A
+> status question ("what's still pending?") touches no file, so no post-tool hook ever fired for it
+> and an agent answered from stale notes. `lemma init` now also installs a `UserPromptSubmit` hook
+> that names the memories bearing on the prompt (with age and freshness) and reminds the agent to
+> verify live git/CI state for status questions. `store_memory` takes `refs` — a commit, or an MR /
+> issue with the state it asserts — and `verify_memory` checks them (`git`, `gh`, `glab`; anything it
+> cannot read is `unverified`, never `fresh`). Also: `search_memory` shows each hit's age and lists
+> below-floor near-misses as orientation only, `get_memory` stops saying "tracks nothing" for
+> claim-tracked entries, `lemma-checkpoint` leaves a store draft the next prompt surfaces once, and a
+> stale MCP build is reported by the prompt hook. Re-run `lemma init` after updating.
+>
+> **🆕 v1.34.0 — Dashboard fixes.** The header shows the real running version (from `/health`), the debugger's pause/resume now works against the proxy, the Vite dev proxy points at the right port, and `npm run build` rebuilds the dashboard so the published UI is never stale.
+>
 > **🆕 v1.33.0 — C# (.NET) support, honestly labeled.** New per-project language detection
 > (`.csproj/.sln`, target frameworks, mixed repos) and a read-only `capability_matrix` tool so clients
 > stop guessing what works outside TypeScript. `get_ast_hologram` and `get_symbol_surgical_context` now
@@ -170,6 +183,14 @@ lemma start     # gateway + dashboard on http://localhost:8081
   are recovered from the command; OpenCode gets a plugin, since it has no hook protocol.
   Windsurf/Devin post-hooks can't inject context, and Kiro's hooks spend tokens by design, so
   neither is wired.
+- **Recall before the agent answers, and memories that know when the world moved** — a
+  `UserPromptSubmit` hook (`lemma-brain-ingest --prompt-submit`, Claude Code) points at the
+  memories a prompt substantially covers and, for status-style questions, says to verify live state
+  first: file-hash freshness can't see an MR merge. `store_memory` / `update_memory` accept
+  `refs` (`{kind:'commit',sha}`, or `{kind:'mr'|'issue',provider,id,state}`), and `verify_memory`
+  checks them with `git` / `gh` / `glab` — stale when they moved, `unverified` (never `fresh`) when
+  they can't be read. The session-end checkpoint leaves a one-shot reminder to store what was
+  verified.
 - **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
@@ -292,6 +313,7 @@ lemma_toolbox { "action": "call",   "tool":  "terraform_drift", "args": {} }
 | `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] [--team-pull]` | Feed The Brain from git commits and `CHANGELOG.md`, incrementally; `--team-pull` imports the repo's `.lemma-brain/`. |
+| `lemma-brain-ingest --prompt-submit` | Read a Claude Code `UserPromptSubmit` payload on stdin and reply with the memories that bear on the prompt (id, age, freshness) plus, for a "what is pending" question, a reminder to verify live git/CI state — or nothing. Also surfaces the last session's store draft and a stale MCP build, once each. |
 | `lemma-brain-ingest --hook-result [--host=claude\|codex\|cursor\|opencode]` | Read a host post-tool payload on stdin: capture red → green fixes from the agent's own shell, and reply with a Brain note (memory ids, failed attempts, known fixes) in that host's format — or nothing. |
 
 Wire the standalone bins into hooks so memory doesn't depend on the assistant remembering to call a tool:
@@ -309,6 +331,23 @@ Wire the standalone bins into hooks so memory doesn't depend on the assistant re
   "hooks": [{ "type": "command", "command": "lemma-brain-ingest --hook-result" }] }] } }
 ```
 
+```jsonc
+// …and the same file gets the recall-before-answer hook (no matcher: it fires on every prompt)
+{ "hooks": { "UserPromptSubmit": [{ "hooks": [{ "type": "command",
+  "command": "lemma-brain-ingest --prompt-submit" }] }] } }
+```
+
+Attach external state when you store something whose truth depends on it, so `verify_memory` can
+tell when it goes stale:
+
+```jsonc
+// store_memory arguments (excerpt)
+{ "refs": [
+  { "kind": "commit", "sha": "2c8a8cb" },                                  // holds while an ancestor of HEAD
+  { "kind": "mr", "provider": "gitlab", "id": "1061", "state": "merged" }  // stale once its state differs
+] }
+```
+
 Codex (`~/.codex/hooks.json`, `--host=codex`), Cursor (`~/.cursor/hooks.json`, `postToolUse` +
 `postToolUseFailure`, `--host=cursor`) and OpenCode (a plugin in `~/.config/opencode/plugins/`) are
 wired the same way by `lemma init` when their config directory exists. Existing hooks are kept;

package/bin/brain-ingest.js

@@ -15,6 +15,7 @@
  *
  * Usage: lemma-brain-ingest [projectRoot] [--max N] [--changelog] [--no-commits] [--team-pull]
  *        lemma-brain-ingest --hook-result [--host=claude|codex|cursor|opencode] < payload.json
+ *        lemma-brain-ingest --prompt-submit < 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 shape) and:
@@ -29,6 +30,13 @@
  *               `lemma init` wires it for each host it finds, e.g. .claude/settings.local.json:
  *                 "hooks": { "PostToolUse": [{ "matcher": "Bash|Read|Edit|MultiEdit|Write|NotebookEdit",
  *                   "hooks": [{ "type": "command", "command": "lemma-brain-ingest --hook-result" }] }] }
+ * --prompt-submit Read a Claude Code UserPromptSubmit payload on stdin and answer with the
+ *               Brain's memories that bear on the prompt (ids, age, freshness) plus, for a
+ *               "what is pending" style question, a reminder to verify live state with
+ *               git/gh/glab. This is the recall point that exists before the agent answers: a
+ *               status question touches no file, so no PostToolUse hook ever fires for it.
+ *               Silent when nothing matches. Wired by `lemma init` in
+ *               .claude/settings.local.json under hooks.UserPromptSubmit.
  */
 
 const path = require('path');
@@ -72,8 +80,28 @@ function hookResult(args) {
   if (out) process.stdout.write(out);
 }
 
+function promptSubmit() {
+  const dist = path.join(__dirname, '..', 'dist', 'cjs');
+  let recallForPrompt, formatHostOutput;
+  try {
+    ({ recallForPrompt } = require(path.join(dist, 'subconscious', 'HostRecall.js')));
+    ({ formatHostOutput } = require(path.join(dist, 'subconscious', 'HostAdapters.js')));
+  } catch {
+    return; // no build — a hook must stay silent and harmless
+  }
+  let payload;
+  try {
+    payload = JSON.parse(readStdin());
+  } catch {
+    return;
+  }
+  const out = formatHostOutput('claude', recallForPrompt(payload, payload && payload.cwd, undefined, { mcpEntry: path.join(dist, 'mcp', 'index.js') }), 'UserPromptSubmit');
+  if (out) process.stdout.write(out);
+}
+
 function main() {
   const args = process.argv.slice(2);
+  if (args.includes('--prompt-submit')) return promptSubmit();
   if (args.includes('--hook-result')) return hookResult(args);
   const maxIndex = args.indexOf('--max');
   const maxCommits = maxIndex >= 0 ? parseInt(args[maxIndex + 1], 10) : undefined;

package/bin/checkpoint.js

@@ -35,6 +35,12 @@ function main() {
     console.error('[lemma-checkpoint] Not a git repository — nothing to capture.');
     return;
   }
+  // Leave a draft for the next session's first prompt: a SessionEnd hook can't speak to the
+  // model, and what was verified this session is exactly what a later status question needs.
+  try {
+    const { writeStoreDraft } = require(path.join(__dirname, '..', 'dist', 'cjs', 'utils', 'StoreDraft.js'));
+    writeStoreDraft(projectRoot);
+  } catch { /* the draft is a courtesy */ }
   console.error(
     `[lemma-checkpoint] Saved: ${result.filesModified.length} file(s) changed → ${path.join(projectRoot, '.lemma/session')}`
   );

package/dashboard/README.md

@@ -1,351 +1,47 @@
 # Lemma Dashboard
 
-Real-time visualization and monitoring dashboard for the Lemma agent orchestration hub.
+Live view of a running Lemma proxy: token savings, cache behaviour, connected agents, MCP
+activity and the Brain's knowledge base.
 
-## Features
+The proxy serves the production build itself at `http://localhost:8081/dashboard/`
+(`lemma start`). The version shown in the header comes from the proxy's `/health`.
 
-### 1. Agent Graph
-- Live visualization of connected agents
-- Node graph showing agent relationships
-- Real-time status updates (active, idle, busy)
-- Agent capabilities display
-- Connection lines to central hub
+## Panels
 
-### 2. Token Economics
-- Real-time cost savings tracking
-- Token usage metrics
-- Cache hit rate visualization
-- Performance charts:
-  - Cache performance over time
-  - Latency trends
-  - Cumulative cost savings
-- ROI calculator with projections
+- **Metrics bar / charts** — requests, hit rate, latency, tokens and cost saved
+  (`/api/metrics`, `/api/cache-stats`, `/api/savings-breakdown`).
+- **The Hub** — connected agents (`/api/agents`), charts, savings breakdown, Brain knowledge
+  stats (`/api/brain/stats`), cache stats and the event timeline (`/api/events`).
+- **The Tools** — live feed of MCP tool calls; the header badge shows MCP status
+  (`/api/mcp-status`) and toggles it (`/api/mcp/toggle`).
+- **The Brain** — semantic search over the cache (`/api/search`).
+- **Debugger** (bottom panel) — pause/resume. While paused the proxy refuses new completions
+  with `503` + `Retry-After` (`/api/debugger/pause|resume|state`).
+- **Flush Cache** — `/api/cache/clear`.
 
-### 3. Time-Travel Debugger
-- Event timeline with all agent interactions
-- State inspector for any point in time
-- Playback controls (pause, step back/forward)
-- State editing capabilities
-- Event filtering by type
+`TimeTravel.tsx` and the rewind call (`/api/debugger/rewind`) exist in the code but are not
+wired into the proxy: rewind is only implemented by the standalone API server
+(`src/api/dashboardRoutes.ts`).
 
-## Quick Start
-
-### Installation
+## Develop
 
 ```bash
-cd dashboard
 npm install
+npm run dev        # Vite on http://localhost:8082/dashboard/
 ```
 
-### Development
-
-```bash
-npm run dev
-```
-
-Dashboard will be available at `http://localhost:3000`
+The dev server talks to the proxy on `http://localhost:8081` (start it with `lemma start`).
+Override with `VITE_API_URL` / `VITE_WS_URL` in `.env`.
 
-### Production Build
+## Build
 
 ```bash
-npm run build
-npm run preview
-```
-
-## Configuration
-
-Create a `.env` file:
-
-```env
-VITE_ROUTER_URL=ws://localhost:8080
-VITE_API_URL=http://localhost:8080
-```
-
-## Architecture
-
-### Tech Stack
-
-- **React 18**: UI framework
-- **TypeScript**: Type safety
-- **Vite**: Build tool and dev server
-- **TailwindCSS**: Styling
-- **Recharts**: Data visualization
-- **Zustand**: State management
-- **WebSocket**: Real-time communication
-
-### Project Structure
-
-```
-dashboard/
-├── src/
-│   ├── components/
-│   │   ├── AgentGraph.tsx      # Agent visualization
-│   │   ├── MetricsPanel.tsx    # Token economics
-│   │   ├── TimeTravel.tsx      # State debugger
-│   │   ├── ConnectionStatus.tsx # WebSocket status
-│   │   └── Layout.tsx          # App layout
-│   ├── hooks/
-│   │   └── useWebSocket.ts     # WebSocket connection
-│   ├── App.tsx                 # Main app component
-│   ├── main.tsx               # Entry point
-│   └── index.css              # Global styles
-├── index.html
-├── package.json
-├── tsconfig.json
-├── vite.config.ts
-└── tailwind.config.js
-```
-
-## WebSocket Protocol
-
-The dashboard connects to the Lemma router via WebSocket and exchanges IAP (Inter-Agent Protocol) messages.
-
-### Connection
-
-```typescript
-const ws = new WebSocket('ws://localhost:8080');
-
-// Send handshake
-ws.send(JSON.stringify({
-  type: 'HANDSHAKE',
-  messageId: crypto.randomUUID(),
-  timestamp: Date.now(),
-  payload: {
-    agentId: 'dashboard-client',
-    agentName: 'Dashboard',
-    version: '1.0.0',
-    capabilities: [{ name: 'monitoring', version: '1.0.0' }],
-  },
-}));
+npm run build      # tsc + vite build -> dist/
 ```
 
-### Message Types
-
-#### Metrics Update
-```json
-{
-  "type": "METRICS_UPDATE",
-  "payload": {
-    "totalRequests": 1000,
-    "cacheHits": 800,
-    "cacheMisses": 200,
-    "averageLatency": 45.2,
-    "tokensSaved": 150000,
-    "costSaved": 0.3,
-    "hitRate": "80.0%"
-  }
-}
-```
-
-#### Agent Connected
-```json
-{
-  "type": "AGENT_CONNECTED",
-  "payload": {
-    "id": "agent-123",
-    "name": "Research Agent",
-    "capabilities": ["research", "analysis"],
-    "status": "idle",
-    "connectedAt": 1234567890
-  }
-}
-```
-
-#### State Event
-```json
-{
-  "type": "STATE_EVENT",
-  "payload": {
-    "id": "event-uuid",
-    "timestamp": 1234567890,
-    "type": "TASK_REQUEST",
-    "agentId": "agent-123",
-    "data": {},
-    "snapshot": {}
-  }
-}
-```
-
-## Components
-
-### AgentGraph
-
-Visualizes the agent swarm as a node graph.
-
-**Props:**
-- `agents: Agent[]` - Array of connected agents
-
-**Features:**
-- Circular layout around central hub
-- Color-coded status indicators
-- Capability badges
-- Connection lines with animation
-
-### MetricsPanel
-
-Displays token economics and performance metrics.
-
-**Props:**
-- `metrics: Metrics` - Current metrics object
-
-**Features:**
-- 6 key metric cards
-- 3 interactive charts
-- ROI calculator
-- Historical data tracking
-
-### TimeTravel
-
-State debugger with time-travel capabilities.
-
-**Props:**
-- `events: StateEvent[]` - Array of captured events
-
-**Features:**
-- Event timeline
-- State inspector
-- Playback controls
-- State editing
-
-### ConnectionStatus
-
-Shows WebSocket connection status.
-
-**Props:**
-- `isConnected: boolean` - Connection state
-
-## Customization
-
-### Theme
-
-Edit `tailwind.config.js` to customize colors:
-
-```javascript
-theme: {
-  extend: {
-    colors: {
-      primary: { /* your colors */ },
-      success: { /* your colors */ },
-      // ...
-    },
-  },
-}
-```
-
-### Metrics
-
-Add custom metrics in `useWebSocket.ts`:
-
-```typescript
-export interface Metrics {
-  // ... existing metrics
-  customMetric: number;
-}
-```
-
-### Charts
-
-Add new charts in `MetricsPanel.tsx` using Recharts:
-
-```typescript
-<LineChart data={historicalData}>
-  <Line dataKey="customMetric" stroke="#color" />
-</LineChart>
-```
-
-## Performance
-
-### Optimizations
-
-- **Lazy Loading**: Components loaded on-demand
-- **Memoization**: React.memo for expensive components
-- **Virtual Scrolling**: For large event lists
-- **Data Limiting**: Keep only recent data points
-
-### Metrics
-
-- **Bundle Size**: ~200KB gzipped
-- **Initial Load**: <1s on fast connection
-- **Memory Usage**: ~50MB typical
-- **CPU Usage**: <5% idle, <15% active
-
-## Deployment
-
-### Static Hosting
-
-Build and deploy to any static host:
-
-```bash
-npm run build
-# Upload dist/ folder to:
-# - Vercel
-# - Netlify
-# - AWS S3 + CloudFront
-# - GitHub Pages
-```
-
-### Docker
-
-```dockerfile
-FROM node:20-alpine AS builder
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci
-COPY . .
-RUN npm run build
-
-FROM nginx:alpine
-COPY --from=builder /app/dist /usr/share/nginx/html
-EXPOSE 80
-CMD ["nginx", "-g", "daemon off;"]
-```
-
-### Environment Variables
-
-Set in deployment platform:
-
-- `VITE_ROUTER_URL`: WebSocket URL of Lemma router
-- `VITE_API_URL`: HTTP API URL (if different)
-
-## Troubleshooting
-
-### WebSocket Connection Failed
-
-1. Check router is running
-2. Verify URL in `.env`
-3. Check CORS settings
-4. Verify firewall rules
-
-### Metrics Not Updating
-
-1. Check WebSocket connection status
-2. Verify router is broadcasting metrics
-3. Check browser console for errors
-4. Verify message format
-
-### Charts Not Rendering
-
-1. Check data format matches Recharts requirements
-2. Verify ResponsiveContainer has height
-3. Check for console errors
-4. Verify data is not empty
-
-## Development
-
-### Adding a New Tab
-
-1. Create component in `src/components/`
-2. Add tab button in `App.tsx`
-3. Add route in tab navigation
-4. Update state management
-
-### Adding a New Metric
-
-1. Update `Metrics` interface in `useWebSocket.ts`
-2. Add metric card in `MetricsPanel.tsx`
-3. Update backend to send metric
-4. Add to historical data tracking
+From the repo root, `npm run build` also builds the dashboard. `dashboard/dist` is
+git-ignored but published to npm, so rebuild before releasing.
 
-## License
+## Stack
 
-MIT
+React 18, TypeScript, Vite, Tailwind, Zustand, Recharts, Socket.IO client.