@unerr-ai/unerr 0.2.7 → 0.2.8

package/README.md

@@ -1,15 +1,17 @@
-<p align="center">
-  <a href="https://www.unerr.dev/"><img src="https://unerr.dev/icon-wordmark.svg" alt="unerr — operational intelligence for your codebase" width="320" /></a>
-</p>
+<h1 align="center">
+  <a href="https://www.unerr.dev/"><img src="https://unerr.dev/icon-wordmark.svg" alt="unerr" width="320" /></a>
+</h1>
 
 <p align="center">
-  <strong>Your AI agent has read your codebase. It was never briefed on it.</strong>
+  <strong>Your AI agent has read your codebase. It still can't safely change it.</strong>
 </p>
 
 <p align="center">
-  <strong>unerr is operational intelligence for your codebase</strong> — the lived history your team carries in its head:<br/>
-  what's been tried, what broke, what the team decided. One local runtime, <em>behind</em> every MCP your agent already speaks,<br/>
-  that hands the agent that judgment the moment it starts working — instead of letting it relearn your repo, every session.
+  On a large, existing codebase your agent can't hold the whole thing in context — so it breaks callers it never read<br/>
+  and rebuilds patterns your team already standardized, even with the rule written down. <strong>unerr is a guardrail<br/>
+  your agent reaches over MCP</strong> that, the moment it edits, hands it the live call graph <em>plus the rule you pinned to that<br/>
+  exact function</em> — a rule that re-anchors itself when the code moves instead of going stale. So it sees the 24 callers,<br/>
+  and the standard it's about to violate, <em>before</em> it touches the function.
 </p>
 
 <p align="center">
@@ -32,38 +34,59 @@
 </p>
 
 <p align="center">
-  <sub>Measured, not estimated: the agent lands on the right code while spending <strong>86–90% fewer tokens</strong> getting there —<br/>
-  same corpus, same tokenizer, with a fidelity gate that discards any "saving" that lost the answer. <a href="./benchmarks/README.md">See the benchmarks →</a></sub>
+  <sub><strong>It nets your context down, not up.</strong> Five separate MCP servers burn ~55K tokens of schemas just to announce themselves;<br/>
+  unerr is one runtime whose tools load on demand, and each edit injects a single scoped line — the rule for the entity in front of it.<br/>
+  Measured: the agent lands on the right code with <strong>86–90% fewer tokens</strong>, same corpus, same tokenizer, with a fidelity gate<br/>
+  that discards any "saving" that lost the answer. <a href="./benchmarks/README.md">See the benchmarks →</a></sub>
 </p>
 
 ---
 
-## The old way is over
+<details>
+<summary><strong>Contents</strong></summary>
+
+- [Agents read your code. They can't safely change it.](#agents-read-your-code-they-cant-safely-change-it)
+- [The pains this fixes](#the-pains-this-fixes)
+- [What changes when you install it](#what-changes-when-you-install-it)
+- [See it in action](#see-it-in-action)
+- [Quick Start](#quick-start)
+- [Who it's for](#who-its-for)
+- [Why one runtime, not five separate tools](#why-one-runtime-not-five-separate-tools)
+- [How the runtime works](#how-the-runtime-works)
+- [License](#license)
+
+</details>
+
+---
+
+## Agents read your code. They can't safely change it.
+
+On a small or greenfield project the agent holds the whole repo in its head and grepping the live code is enough — you don't need us. The wall is the *large, existing, multi-contributor* codebase, and it's the same wall every time: the agent can't fit the whole thing in context, so it acts on the slice it can see and never reads the rest.
 
-Coding agents now write the code. They've read every line of your repo — and not one of them has been briefed on it. They don't know what the team tried here and abandoned, why this function drifted, what broke the last time someone touched it, or which decision is load-bearing. A new engineer gets that briefing on day one. The agent starts cold, every single session.
+So it ships damage that looks locally correct. It changes a signature and breaks the 24 callers it never read. It writes a fourth copy of a registry pattern your team standardized months ago — even with the rule spelled out in `.cursorrules`. Neither shows up as an error. They show up as a senior engineer's afternoon.
 
-So it guesses. It greps where a senior engineer would check the call graph. It re-derives on Tuesday what it worked out on Monday. And the knowledge that *would* brief it — who changed each file and why, what failed before, the conventions the team accreted — is scattered across one tool for memory, another for the graph, a third for context, none of which can reach across the others.
+The knowledge that would have stopped it — who calls this function, which pattern is load-bearing — exists. It's just nowhere the agent can reach *at the moment it edits*: in a call graph it doesn't build, and conventions it was never told.
 
-**unerr is the layer that ends the guessing.** One per-repo runtime, behind every MCP your agent already speaks, that carries your codebase's lived history and hands the agent that judgment the moment it starts — so it lands on the right code without burning turns, and sees what a change will break before it breaks it.
+**unerr is the guardrail that closes that gap.** One local runtime your agent reaches over MCP, that hands it the call graph and the rules you anchored to each entity the moment it edits — and re-anchors those rules when the code moves, so they never go silently stale. A change that would break 7 call sites is caught before it lands; a standard you set once is enforced every time the agent touches that scope.
 
 | The old way | With unerr |
 |---|---|
-| The agent refactors a function blind to its 24 callers — 7 sites break silently. | **Cascade guard** reads the call graph *before* the edit; every caller is on screen first. |
-| Conventions and decisions live in `MEMORY.md` / `.cursorrules` you hand-maintain and re-paste each session. | **Anchored memory + drift detection** — facts pin to the code and get a drift signal when it moves, instead of going silently stale. |
-| Five single-purpose MCP servers — memory, graph, compressor — that can't reach across each other. | **One runtime** — so cascade guard, convention drift, and loop breaker fire on joins no point tool can make. |
+| The agent changes a function without reading its 24 callers — 7 sites break silently. | **Cascade guard** reads the call graph *before* the edit; every caller is on screen first. |
+| The agent ships a fourth copy of a pattern your team standardized — the rule in `.cursorrules` was never honored. | **Anchored rules** surface the standard the moment the agent touches that scope, and re-anchor when the code moves instead of going silently stale. |
+| Five single-purpose MCP servers — memory, graph, compressor — that can't reach across each other. | **One runtime** — cascade guard, convention drift, and a loop breaker (*stops the agent re-trying a fix that already failed twice*) fire on joins no point tool can make. |
 
 ---
 
 ## The pains this fixes
 
-You've felt all four of these in the last 48 hours:
+If you're maintaining a large, existing codebase, you've hit these — and they get *worse* as the repo grows, not better:
 
-- Claude is brilliant for 20 minutes, then hallucinates a duplicate component and forgets the styling rules you set five turns ago.
-- More time spent writing `MEMORY.md`, updating `.cursorrules`, and pasting session summaries than writing code.
-- The agent reads a 2,000-line file to find a 5-line function, then still doesn't know that function has 24 callers in six other files.
-- You don't trust the agent to refactor anything important. It treats your codebase like a flat string of text — locally correct, globally wrong.
+- The agent is sharp for 20 minutes, then writes a second implementation of something you already have, because it never saw the first.
+- You don't trust it to change anything load-bearing. It treats your codebase as a flat string of text — locally correct, globally wrong.
+- It reads a 2,000-line file to find a 5-line function, then still doesn't know that function has 24 callers in six other files.
+- The rule you wrote in `.cursorrules` gets acknowledged, then ignored a few turns later once the context fills up.
 
-These aren't four problems. They're one: **your agent acts on your codebase without ever having been briefed on it.** It greps where a senior engineer would check the call graph, and it relearns on Tuesday what it worked out on Monday.
+These aren't four problems. They're one: **your agent acts on a codebase it can't hold in context, with no idea what each change will break or which rule it's about to violate.**
 
 ---
 
@@ -72,7 +95,7 @@ These aren't four problems. They're one: **your agent acts on your codebase with
 | You feel | What unerr does |
 |---|---|
 | **Trust returns.** The agent runs for an hour without you watching. | Every edit is preceded by a graph lookup. All 24 callers are visible *before* it touches the function. Refactors stop rippling silently. |
-| **The babysitter tax disappears.** You delete `MEMORY.md` and `.cursorrules`. | A local fact store remembers what you decided, what failed, and the conventions the team accreted — with decay-adjusted confidence. Open the laptop on Tuesday and the agent already knows what you decided on Monday. |
+| **Your rules finally get honored.** The standard you set is enforced at the edit, not acknowledged and forgotten once context fills up. | unerr anchors each rule and decision to the file or entity it governs and surfaces it the instant the agent touches that scope — then re-anchors it when the code moves, so it never goes silently stale. Keep your `.cursorrules` and specs; unerr makes sure they're applied. |
 | **The agent stays sharp at turn 50.** | `file_read({entity})` returns 200 lines instead of 3,000. Shell output is compressed 93% on average. The context window stays uncluttered, so the model isn't fighting "lost in the middle." |
 | **Tool sprawl dies.** | One graph, one set of tools, project-aware routing. Five MCP servers no longer compete for the agent's attention. |
 
@@ -163,9 +186,9 @@ Close and reopen your IDE (or start a new chat session). Your agent picks up une
 
 ## Who it's for
 
-- **Vibe coders.** The thing that stops your app from breaking on turn 30 when the AI gets confused.
-- **Solo builders.** The continuous thread. Switch from Claude Code in the terminal to Cursor in the IDE — your project memory comes with you.
-- **Senior / staff engineers.** The dependency graph, prior incidents, and team conventions a human engineer would already carry in their head — fed to AI on every edit.
+- **Engineers on large, existing codebases.** The dependency graph, the load-bearing patterns, and the prior incidents a senior engineer carries in their head — handed to the agent before every edit, so it stops breaking callers it never read.
+- **Teams with conventions worth enforcing.** The standard you agreed on once, applied every time the agent touches that scope — no `.cursorrules` file to hand-maintain, re-paste, or merge-conflict over.
+- **Solo builders shipping into a codebase that's already grown.** The continuous thread across tools — switch from Claude Code in the terminal to Cursor in the IDE and the graph, rules, and history come with you, instead of relearning the repo every session.
 
 ---
 

package/dist/cli.js

@@ -5639,13 +5639,13 @@ var init_temporal_facts = __esm({
       session_analysis: 0.6,
       user_fed: 0.95
     };
-    MAX_CONTENT_LENGTH = 500;
+    MAX_CONTENT_LENGTH = 1400;
     TYPE_CONTENT_LIMITS = {
-      convention: 600,
-      semantic: 500,
-      episodic: 800,
-      procedural: 400,
-      negative: 400
+      convention: 1400,
+      semantic: 1400,
+      episodic: 1600,
+      procedural: 1400,
+      negative: 1400
     };
     TemporalFactStore = class _TemporalFactStore {
       constructor(db, config) {
@@ -12996,12 +12996,12 @@ function formatSessionResumeBlock(payload) {
   );
   if (payload.last_intents && payload.last_intents.length > 0) {
     const intent = payload.last_intents[0];
-    if (intent) parts.push(`\u25B8 last intent: ${intent.text}`);
+    if (intent) parts.push(`\u25B8 last intent: ${truncateForStrip(intent.text)}`);
   }
   if (payload.open_blockers && payload.open_blockers.length > 0) {
     for (const b of payload.open_blockers.slice(0, 3)) {
       const anchor = b.file_path ? ` [${b.file_path}]` : "";
-      parts.push(`\u25B8 unresolved blocker: ${b.text}${anchor}`);
+      parts.push(`\u25B8 unresolved blocker: ${truncateForStrip(b.text)}${anchor}`);
     }
   }
   if (payload.broken_callers && payload.broken_callers.length > 0) {
@@ -13031,6 +13031,10 @@ function formatSessionResumeBlock(payload) {
   const result = parts.join("\n");
   return result.length > 500 ? `${result.slice(0, 497)}...` : result;
 }
+function truncateForStrip(text2, max = 100) {
+  const t = text2.trim();
+  return t.length > max ? `${t.slice(0, max - 1)}\u2026` : t;
+}
 function formatElapsed(ms) {
   const minutes = Math.floor(ms / 6e4);
   if (minutes < 60) return `${minutes}m`;
@@ -26756,27 +26760,27 @@ var init_tool_descriptions = __esm({
       // ── Tier 3 — intent unlock ─────────────────────────────────────────────
       mark_intent: {
         tier: 3,
-        active: "REQUIRED first on coding tasks (implement/fix/refactor/build). \u226480 chars summary. Skip only for read-only questions. Powers resume strip.",
-        locked: "[locked, unlock: first non-trivial action] REQUIRED first on coding tasks. \u226480 chars summary.",
-        unlocked: "REQUIRED first on coding tasks. \u226480 chars summary. One per task; powers turn titles + cross-session resume."
+        active: "REQUIRED first on coding tasks (implement/fix/refactor/build). 1 terse sentence. Skip only for read-only questions. Powers resume strip.",
+        locked: "[locked, unlock: first non-trivial action] REQUIRED first on coding tasks. 1 terse sentence.",
+        unlocked: "REQUIRED first on coding tasks. 1 terse sentence. One per task; powers turn titles + cross-session resume."
       },
       mark_decision: {
         tier: 3,
-        active: "Record a deliberate choice between alternatives (\u2264140 chars). Optional list of considered alternatives.",
+        active: "Record a deliberate choice between alternatives (1-2 sentences, \u22641400 chars). Optional list of considered alternatives.",
         locked: "[locked, unlock: after mark_intent] Record a deliberate choice between alternatives.",
-        unlocked: "Record a deliberate choice (\u2264140 chars). Optional alternatives list (\u22645, each \u226480 chars). Surfaces in timeline."
+        unlocked: "Record a deliberate choice (1-2 sentences, \u22641400 chars). Optional alternatives list (\u22645, each \u226480 chars). Surfaces in timeline."
       },
       mark_blocker: {
         tier: 3,
-        active: "Record an unresolved obstacle (\u2264140 chars). Returned marker_id is required by mark_resolution when fixed.",
+        active: "Record an unresolved obstacle (1-2 sentences, \u22641400 chars). Returned marker_id is required by mark_resolution when fixed.",
         locked: "[locked, unlock: after mark_intent] Record an unresolved obstacle.",
-        unlocked: "Record an obstacle (\u2264140 chars). Returned marker_id must be passed to mark_resolution when fixed. Surfaces in resume."
+        unlocked: "Record an obstacle (1-2 sentences, \u22641400 chars). Returned marker_id must be passed to mark_resolution when fixed. Surfaces in resume."
       },
       mark_resolution: {
         tier: 3,
         active: "Resolve a prior blocker. blocker_ref is the marker_id from mark_blocker; text describes the fix.",
         locked: "[locked, unlock: after mark_blocker] Resolve a prior blocker.",
-        unlocked: "Resolve a prior blocker. blocker_ref is the marker_id from mark_blocker. Text (\u2264140 chars) describes the fix."
+        unlocked: "Resolve a prior blocker. blocker_ref is the marker_id from mark_blocker. Text (1-3 sentences, \u22641400 chars) describes the fix."
       },
       recall_facts: {
         tier: 3,
@@ -27238,7 +27242,7 @@ var init_tool_definitions = __esm({
           properties: {
             text: {
               type: "string",
-              description: "One short sentence describing the task (\u226480 chars)."
+              description: "Task in 1 terse sentence. Hard cap 1400 chars; be concise."
             }
           },
           required: ["text"]
@@ -27255,7 +27259,7 @@ var init_tool_definitions = __esm({
           properties: {
             text: {
               type: "string",
-              description: "One short sentence describing the decision (\u2264140 chars)."
+              description: "Decision in 1-2 sentences. Hard cap 1400 chars; be concise."
             },
             alternatives: {
               type: "array",
@@ -27277,7 +27281,7 @@ var init_tool_definitions = __esm({
           properties: {
             text: {
               type: "string",
-              description: "One short sentence describing the blocker (\u2264140 chars)."
+              description: "Blocker in 1-2 sentences. Hard cap 1400 chars; be concise."
             },
             file_path: {
               type: "string",
@@ -27302,7 +27306,7 @@ var init_tool_definitions = __esm({
             },
             text: {
               type: "string",
-              description: "One short sentence describing the resolution (\u2264140 chars)."
+              description: "What fixed the blocker, in 1-3 sentences. Hard cap 1400 chars."
             }
           },
           required: ["blocker_ref", "text"]
@@ -27425,7 +27429,7 @@ var init_tool_definitions = __esm({
             // ── Legacy free-form (TemporalFactStore) payload ──
             content: {
               type: "string",
-              description: "Normalised statement of the user's fact (max 280 chars). Keep terse."
+              description: "Normalised statement of the user's fact, 1-3 sentences. Hard cap 1400 chars; keep terse."
             },
             source_quote: {
               type: "string",
@@ -28023,9 +28027,9 @@ async function executeRecordFact(args, factStore, sessionId) {
   if (!content || content.trim().length === 0) {
     throw new Error("content is required and cannot be empty");
   }
-  if (content.length > 280) {
+  if (content.length > 1400) {
     throw new Error(
-      `content exceeds 280 character limit (got ${content.length}). Shorten the fact.`
+      `content is ${content.length} chars, exceeds 1400-char cap. Shorten to \u22641400 (1-3 sentences).`
     );
   }
   if (!["procedural", "semantic", "negative", "convention"].includes(fact_type)) {
@@ -28048,11 +28052,8 @@ async function executeRecordFact(args, factStore, sessionId) {
     base_confidence: 0.95
   };
   const { fact_id, deduplicated } = await factStore.createFact(input);
-  const verb = deduplicated ? "Reinforced" : "Recorded";
-  const message = `${verb}: "${content.trim().slice(0, 60)}${content.trim().length > 60 ? "..." : ""}" [${fact_type}] \u2192 ${scope}`;
   return {
     fact_id,
-    message,
     deduplicated
   };
 }
@@ -28193,9 +28194,9 @@ async function executeUnerrRemember(args, factStore, sessionId, turn, behaviorEv
   if (!content || content.trim().length === 0) {
     throw new Error("content is required and cannot be empty");
   }
-  if (content.length > 280) {
+  if (content.length > 1400) {
     throw new Error(
-      `content exceeds 280 character limit (got ${content.length}). Shorten the fact.`
+      `content is ${content.length} chars, exceeds 1400-char cap. Shorten to \u22641400 (1-3 sentences).`
     );
   }
   if (!source_quote || source_quote.trim().length === 0) {
@@ -28248,11 +28249,6 @@ async function executeUnerrRemember(args, factStore, sessionId, turn, behaviorEv
   });
   const ambiguity_flag = confidence < REMEMBER_AMBIGUITY_THRESHOLD;
   const trimmedContent = content.trim();
-  const previewContent = `${trimmedContent.slice(0, 60)}${trimmedContent.length > 60 ? "..." : ""}`;
-  const scopeText = scope.trim() === "project" ? "the whole project" : `\`${scope.trim()}\``;
-  const verb = deduplicated ? "reinforced an existing note" : "added a new note";
-  const tail = ambiguity_flag ? ` \u2014 I'm only ${Math.round(confidence * 100)}% sure I got that right, please confirm or correct` : "";
-  const echo_summary = `unerr ${verb} for ${scopeText}: "${previewContent}"${tail}`;
   if (ambiguity_flag && pendingConfirmations) {
     pendingConfirmations.register({
       fact_id,
@@ -28289,8 +28285,7 @@ async function executeUnerrRemember(args, factStore, sessionId, turn, behaviorEv
     fact_id,
     deduplicated,
     ambiguity_flag,
-    confidence,
-    echo_summary
+    confidence
   };
 }
 var REMEMBER_CONFIDENCE_FLOOR, REMEMBER_AMBIGUITY_THRESHOLD;
@@ -42158,6 +42153,7 @@ var init_loop_breaker = __esm({
 // src/tools/intelligence/timeline-markers.ts
 var timeline_markers_exports = {};
 __export(timeline_markers_exports, {
+  MARKER_TEXT_CAP: () => MARKER_TEXT_CAP,
   MARKER_TOOLS: () => MARKER_TOOLS,
   handleMarkerCall: () => handleMarkerCall,
   isMarkerTool: () => isMarkerTool
@@ -42172,7 +42168,9 @@ async function handleMarkerCall(toolName, args, deps) {
     return errorResult2(`${toolName}: text is required`);
   }
   if (text2.length > cap2) {
-    return errorResult2(`${toolName}: text exceeds ${cap2}-char limit`);
+    return errorResult2(
+      `${toolName}: text is ${text2.length} chars, exceeds ${cap2}-char cap \u2014 shorten to \u2264${cap2}.`
+    );
   }
   const argsToPersist = { text: text2 };
   let blockerRef = "";
@@ -42251,7 +42249,7 @@ function errorResult2(msg) {
     ]
   };
 }
-var MARKER_TOOLS, MARKER_TOOL_SET, TEXT_CAP;
+var MARKER_TOOLS, MARKER_TOOL_SET, MARKER_TEXT_CAP, TEXT_CAP;
 var init_timeline_markers = __esm({
   "src/tools/intelligence/timeline-markers.ts"() {
     "use strict";
@@ -42263,11 +42261,12 @@ var init_timeline_markers = __esm({
       "mark_resolution"
     ];
     MARKER_TOOL_SET = new Set(MARKER_TOOLS);
+    MARKER_TEXT_CAP = 1400;
     TEXT_CAP = {
-      mark_intent: 80,
-      mark_decision: 140,
-      mark_blocker: 140,
-      mark_resolution: 140
+      mark_intent: MARKER_TEXT_CAP,
+      mark_decision: MARKER_TEXT_CAP,
+      mark_blocker: MARKER_TEXT_CAP,
+      mark_resolution: MARKER_TEXT_CAP
     };
   }
 });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@unerr-ai/unerr",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "mcpName": "io.github.unerr-ai/unerr",
-  "description": "Local-first code intelligence CLI for unerr",
+  "description": "Your AI agent has read your codebase but still can't safely change it. unerr is a local guardrail that hands the agent the call graph and your rules at the moment it edits.",
   "repository": {
     "type": "git",
     "url": "https://github.com/unerr-ai/unerr-cli.git"