limen-ai 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,78 @@ All notable changes to Limen are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-04-28 (WIRE)
+
+### Summary
+Complete wiring remediation and production readiness release. Every spec promise verified end-to-end. Every "auto" feature runs automatically. Every security feature enforces.
+
+### Added
+- **Phase 1: Core Wiring** — Decay computation in convenience `recall()` (effectiveConfidence at query time). Automated retention scheduler (background timer, configurable interval). Replay engine integration (mission state snapshots on lifecycle transitions). Auto-connection suggestions (debounced, fires on claim assertion).
+- **Phase 2: Security Enforcement** — Consent enforcement on claim assertion (fail-closed, configurable). Classification-filtered retrieval on query AND search paths (trust-level mapped clearance). Key rotation (atomic re-encryption of vault entries).
+- **Phase 3: MCP Tool Completion** — 11 new MCP tools: `limen_consolidate`, `limen_importance`, `limen_narrative`, `limen_verify`, `limen_suggest_connections`, `limen_replay_verify`, `limen_governance_erasure`, `limen_governance_audit_export`, `limen_consent_register`, `limen_consent_check`, `limen_maintenance_retention`. 11 matching CLI commands. Total: 36 MCP tools.
+- **Phase 4: DX/UX** — README overhaul (Node>=22 banner, ESM note, CLI section, MCP for Claude section, What's New in v3). Examples README with runner instructions.
+- **Phase 5: Proof Pack** — Security model expanded from 8 to 11 mechanisms. Readiness doc refreshed for v3.0.0.
+- **Phase 6: OAT** — 8 operational acceptance scenarios verifying every spec promise end-to-end.
+- `limen.maintenance.runRetention()`, `getRetentionPolicies()`, `updateRetentionPolicy()` — manual retention API
+- `limen.replay.verify(missionId)`, `replay.getSnapshots(missionId)` — mission determinism verification
+- `limen.security.rotateKey(newMasterKey)` — atomic key rotation
+- `maintenance.retentionEnabled`, `maintenance.retentionIntervalMs` config options
+- `security.consent.required`, `security.consent.scope` config options
+- `cognitive.autoSuggestConnections` config option
+
+### Fixed
+- **Dispute recomputation** — `disputed` flag now correctly recomputes to `false` after contradicting claim is retracted (3 sites: queryClaims, searchClaims, vectorHydrateDisputed)
+- **Classification filter bypass** — search path now filters by classification level (was query-only)
+- **Consent fail-open** — consent enforcement now fail-closed when registry unavailable
+- **Replay SQLITE_BUSY** — replay snapshots use orchestrationConn instead of separate connection
+- **Stale worktree/stryker pollution** — cleaned phantom test failures from stale temp directories
+
+### Changed
+- Removed all AI attribution from source code, tests, and documentation
+- `vitest.config.ts` added at root to prevent phantom failures from node:test files
+- Permission gateway updated with maintenance, replay, security namespace registrations
+
+---
+
+## [2.0.0] - 2026-04-03 (THINK)
+
+### Added
+- **Phase 11: Vector Search** — semantic search via `sqlite-vec` (optional dependency). Hybrid search combining FTS5 keyword + vector similarity. Duplicate detection before storage with configurable similarity threshold. Embedding queue with `embedPending()` for batch processing. `embeddingStats()` for monitoring. Falls back to full-text search when `sqlite-vec` is unavailable.
+- **Phase 12: Cognitive Engine** — self-healing retraction cascades (opt-in, disabled by default). Consolidation engine: merge similar claims, archive stale claims, suggest contradiction resolutions with dry-run mode. 5-factor importance scoring (recency, confidence, connections, access, centrality). KNN-based auto-connection suggestions via embedding similarity with accept/reject workflow. Mission-scoped narrative snapshots. External verification provider integration (advisory only, never mutates claims).
+- `limen.semanticSearch(query, options?)` — async semantic search via embedding provider.
+- `limen.checkDuplicate(subject, predicate, value)` — pre-storage duplicate detection.
+- `limen.embedPending()` — process embedding queue for pending claims.
+- `limen.embeddingStats()` — embedding pipeline statistics.
+- `limen.cognitive.consolidate(options?)` — merge, archive, suggest resolutions.
+- `limen.cognitive.importance(claimId, weights?)` — composite importance score.
+- `limen.cognitive.narrative(missionId?)` — knowledge state snapshot.
+- `limen.cognitive.verify(claimId)` — external claim verification (async).
+- `limen.cognitive.suggestConnections(claimId)` — KNN relationship suggestions.
+- `limen.cognitive.acceptSuggestion(id)` / `rejectSuggestion(id)` — suggestion workflow.
+- `selfHealing` configuration: `{ enabled, autoRetractThreshold, maxCascadeDepth }`.
+- `vector` configuration: `{ provider, dimensions }`.
+- Migration v036 (cognitive engine tables: connection_suggestions, consolidation_log).
+
+### Changed
+- **BREAKING:** `SearchOptions.mode` now includes `'semantic' | 'hybrid'` alongside existing `'fulltext'`.
+- **BREAKING:** Major version bump signals cognitive capabilities. No breaking API removals — all v1.x APIs continue to work.
+- `sqlite-vec` added as optional dependency (not required for core functionality).
+
+## [1.5.0] - 2026-04-03 (GOVERN)
+
+### Added
+- **Phase 9: Security Hardening** — PII detection engine with configurable patterns (emails, phone numbers, SSNs, credit cards). Claim content sanitization against prompt injection patterns. FTS5 query injection defense. Subject/predicate URI format validation. Sensitivity levels controlling enforcement (block, redact, log). Consent tracking API (`limen.consent`) with CRUD operations, expiry computation on read, and audit trail on all mutations.
+- **Phase 10: Governance Suite** — Data classification engine with configurable rules. Protected predicate system preventing unauthorized mutation of critical knowledge domains. GDPR Article 17 erasure with cryptographic certificate generation (`limen.governance.erasure()`). SOC 2 Type II audit package export (`limen.governance.exportAudit()`). Classification rule management (`addRule`, `removeRule`, `listRules`). Protected predicate management (`protectPredicate`, `listProtectedPredicates`).
+- `limen.consent.register()` / `revoke()` / `check()` / `list()` — consent lifecycle management.
+- `limen.governance.erasure()` — GDPR erasure with audit certificate.
+- `limen.governance.exportAudit()` — SOC 2 compliance export.
+- `limen.governance.addRule()` / `removeRule()` / `listRules()` — classification rule management.
+- `limen.governance.protectPredicate()` / `listProtectedPredicates()` — predicate access control.
+- Migrations for security tables and governance tables.
+
+### Changed
+- Security controls applied at the claim assertion boundary — PII detection and injection defense run before storage, not after.
+
 ## [1.4.0] - 2026-03-31
 
 ### Added

package/README.md

@@ -14,31 +14,50 @@
 
 # Limen
 
-A governed knowledge engine for AI agents. Beliefs, not data.
+Cognitive infrastructure for AI agents — beliefs that decay, governance that enforces, knowledge that heals itself.
+
+> **Requires Node.js >= 22.** ESM-only package (`"type": "module"`).
 
 ```
 npm install limen-ai
 ```
 
-## Quickstart
+Run with: `npx tsx yourscript.ts`
+
+Optional, for semantic/vector search:
+
+```
+npm install sqlite-vec
+```
+
+## What's New in v3.0.0
+
+- **Decay in recall** — `effectiveConfidence` now decays on every read (was only in search)
+- **Automated retention** — background scheduler cleans expired data automatically
+- **Replay verification** — mission determinism verified via state snapshots
+- **Auto-connection** — relationship suggestions fire automatically on claim assertion
+- **Consent enforcement** — claim assertion blocked without active consent (when configured)
+- **Classification filtering** — claims filtered by clearance level at query and search time
+- **Key rotation** — atomic re-encryption of all vault entries with new master key
+- **11 new MCP tools** — 36 total tools, full CLI parity
+- **Dispute fix** — `disputed` flag correctly recomputes after contradicting claim retracted
+
+## Quick Start
 
 ```typescript
 import { createLimen } from 'limen-ai';
 
 const limen = await createLimen();
 
-// Store a belief
 limen.remember('entity:user:alice', 'preference.food', 'loves Thai food');
 
-// Recall what you know
 const beliefs = limen.recall('entity:user:alice');
 if (beliefs.ok) {
-  console.log(beliefs.value[0].value);            // "loves Thai food"
-  console.log(beliefs.value[0].confidence);        // 0.7 (governed ceiling)
+  console.log(beliefs.value[0].value);              // "loves Thai food"
+  console.log(beliefs.value[0].confidence);          // 0.7 (governed ceiling)
   console.log(beliefs.value[0].effectiveConfidence); // decays over time
 }
 
-// Search across all knowledge
 const results = limen.search('Thai');
 if (results.ok) {
   console.log(results.value[0].belief.value);  // "loves Thai food"
@@ -48,11 +67,17 @@ if (results.ok) {
 await limen.shutdown();
 ```
 
-`createLimen()` with no arguments auto-detects providers, generates a dev encryption key, and provisions a local SQLite database. Copy, paste, run.
+`createLimen()` with no arguments auto-detects LLM providers, generates a dev encryption key, and provisions a local SQLite database. Copy, paste, run. If no LLM provider is configured, core CRUD (remember, recall, search, forget) works in degraded mode — only cognitive features (chat, infer, verify, narrative) require a provider.
+
+## What Makes Limen Different
+
+Most AI memory systems store data — key-value pairs, vector embeddings, chat history. Limen stores **beliefs**.
+
+**Beliefs, not data.** Every claim has a confidence score, a temporal anchor, and a decay curve. A belief stored 90 days ago with no reinforcement is weaker than one stored yesterday. This is computed on every read — nothing is stored. `effectiveConfidence` always reflects the current state of belief.
 
-## Why Limen
+**Governance, not storage.** Auto-extracted claims are capped at 0.7 confidence — the `maxAutoConfidence` ceiling prevents confidence laundering. Structural conflict detection flags contradictions on write. Cascade retraction penalizes downstream beliefs when a source is retracted. PII detection blocks sensitive data before it reaches the database. Protected predicates prevent unauthorized mutation of critical knowledge.
 
-AI agents accumulate knowledge, but most systems store it as flat data -- key-value pairs, vector embeddings, chat history. Knowledge is not data. Knowledge is belief: it has confidence, it decays without reinforcement, it can be contradicted, retracted, and traced back to evidence. Limen treats knowledge this way. Every belief has a confidence score, a temporal anchor, a decay curve, and a governed lifecycle. The engine does not store facts. It manages beliefs.
+**Cognition, not retrieval.** The engine consolidates duplicate beliefs, computes importance scores, suggests connections between claims, generates narrative snapshots of knowledge state, and optionally self-heals by auto-retracting derived claims whose parents have decayed below threshold.
 
 ## Core API
 
@@ -60,23 +85,15 @@ AI agents accumulate knowledge, but most systems store it as flat data -- key-va
 |---|---|
 | `remember(subject, predicate, value, options?)` | Store a belief with confidence and temporal anchoring |
 | `remember(text, options?)` | Store a free-text observation (auto-generates subject) |
-| `recall(subject?, predicate?, options?)` | Retrieve beliefs, filtered by subject/predicate |
+| `recall(subject?, predicate?, options?)` | Retrieve beliefs, filtered by subject/predicate, with decay applied |
 | `search(query, options?)` | Full-text search across all beliefs (FTS5 + BM25) |
-| `forget(claimId, reason?)` | Retract a belief (governed, audited, never deleted) |
+| `forget(claimId, reason?)` | Retract a belief (governed, audited, never deleted). Reason: `'incorrect'` \| `'superseded'` \| `'expired'` \| `'manual'` (default) |
 | `connect(claimId1, claimId2, type)` | Relate beliefs: `supports`, `contradicts`, `supersedes`, `derived_from` |
 | `reflect(entries)` | Batch-store categorized learnings (decisions, patterns, warnings, findings) |
-| `promptInstructions()` | Get system prompt text teaching agents how to use Limen |
-| `cognitive.health(config?)` | Knowledge health report: freshness, conflicts, gaps, stale domains |
-
-## Beliefs That Breathe
-
-Beliefs decay without reinforcement. Limen uses the FSRS power-decay formula: `R(t) = (1 + t/(9*S))^-1`, where `S` is stability in days (governance claims: 365d, findings: 90d, ephemeral: 7d).
 
 ```typescript
-// A belief stored 60 days ago with stability=90d (finding)
-limen.remember('entity:project:limen', 'finding.performance', 'FTS5 queries <5ms at 10K claims');
-
-// 60 days later, recall shows decay
+// Beliefs decay without reinforcement (FSRS power-decay)
+// R(t) = (1 + t/(9*S))^-1, where S is stability in days
 const beliefs = limen.recall('entity:project:limen');
 if (beliefs.ok) {
   const b = beliefs.value[0];
@@ -84,42 +101,210 @@ if (beliefs.ok) {
   console.log(b.effectiveConfidence);  // 0.57 (after 60d decay with S=90)
   console.log(b.freshness);           // "stale" | "aging" | "fresh"
 }
-```
-
-Effective confidence is computed at query time. Nothing is stored. Recall always reflects the current state of belief.
-
-## Safety and Governance
-
-Limen contains wrongness by default. Auto-extracted claims are capped at 0.7 confidence -- the `maxAutoConfidence` ceiling prevents confidence laundering. Structural conflict detection flags contradictions. Cascade retraction penalizes downstream beliefs when a source is retracted.
 
-```typescript
 // Wrongness containment: confidence is capped
 const r = limen.remember('entity:market:ev', 'size.2025', '$45B', { confidence: 0.95 });
-console.log(r.ok && r.value.confidence); // 0.7 (capped, not 0.95)
+// r.value.confidence === 0.7 (capped, not 0.95)
 
-// Conflict detection: contradictions are automatic
+// Conflict detection is automatic
 limen.remember('entity:market:ev', 'size.2025', '$52B');
 // ^ creates a 'contradicts' relationship with the first claim
 
-// Cascade retraction: derived beliefs are penalized
+// Batch-store learnings
+limen.reflect([
+  { category: 'decision', statement: 'Chose FSRS over exponential decay', confidence: 0.85 },
+  { category: 'warning', statement: 'FTS5 trigram index doubles storage', confidence: 0.7 },
+]);
+```
+
+## Cognitive API
+
+The `cognitive` namespace provides knowledge health diagnostics and active knowledge management.
+
+| Method | Description |
+|---|---|
+| `cognitive.health(config?)` | Knowledge health report: freshness distribution, conflicts, gaps, stale domains |
+| `cognitive.consolidate(options?)` | Merge similar claims, archive stale ones, suggest contradiction resolutions |
+| `cognitive.importance(claimId, weights?)` | 5-factor composite importance score for a claim |
+| `cognitive.narrative(missionId?)` | Snapshot of knowledge state — threads, themes, evolution over time |
+| `cognitive.verify(claimId)` | Verify a claim via external provider (async, advisory only) |
+| `cognitive.suggestConnections(claimId)` | KNN-based relationship suggestions via embedding similarity |
+| `cognitive.acceptSuggestion(id)` | Accept a pending connection suggestion |
+| `cognitive.rejectSuggestion(id)` | Reject a pending connection suggestion |
+
+```typescript
+// Knowledge health diagnostics
 const health = limen.cognitive.health();
 if (health.ok) {
-  console.log(health.value.conflicts.unresolved); // 1 active conflict
-  console.log(health.value.freshness);             // { fresh: N, aging: N, stale: N }
+  console.log(health.value.totalClaims);          // total active claims
+  console.log(health.value.freshness);           // { fresh: N, aging: N, stale: N }
+  console.log(health.value.conflicts.unresolved); // unresolved contradictions
+  console.log(health.value.gaps);                // predicates with no recent claims
+}
+
+// Consolidation: merge duplicates, archive stale, suggest resolutions
+const result = limen.cognitive.consolidate({ dryRun: true });
+if (result.ok) {
+  console.log(result.value.merged);               // claims merged
+  console.log(result.value.archived);             // claims archived
+  console.log(result.value.suggestedResolutions); // contradiction resolutions
+}
+
+// Importance scoring
+const score = limen.cognitive.importance(claimId);
+if (score.ok) {
+  console.log(score.value.score);      // 0.0-1.0 weighted composite
+  console.log(score.value.factors);    // { accessFrequency, recency, connectionDensity, confidence, governanceWeight }
+}
+
+// Knowledge narrative
+const narrative = limen.cognitive.narrative();
+if (narrative.ok) {
+  console.log(narrative.value.threads);    // thematic threads across claims
+  console.log(narrative.value.momentum);  // 'growing' | 'stable' | 'declining'
 }
 ```
 
-## Under the Hood
+## Governance API
+
+Classification, access control, compliance, and audit infrastructure.
+
+| Method | Description |
+|---|---|
+| `governance.erasure(request)` | GDPR Article 17 erasure with certificate generation |
+| `governance.exportAudit(options)` | SOC 2 Type II audit package export |
+| `governance.addRule(rule)` | Add a data classification rule |
+| `governance.removeRule(ruleId)` | Remove a classification rule |
+| `governance.listRules()` | List all active classification rules |
+| `governance.protectPredicate(rule)` | Protect a predicate from unauthorized mutation |
+| `governance.listProtectedPredicates()` | List all protected predicate rules |
 
-16 system calls. 134 invariants across 3 tiers. 3,400+ tests. 1 production dependency (`better-sqlite3`). Every state mutation is audited in a hash-chained, append-only trail. RBAC on every operation. AES-256-GCM encryption at rest. Tenant isolation at row or database level.
+```typescript
+// GDPR erasure with audit certificate
+const erasure = limen.governance.erasure({
+  dataSubjectId: 'user:alice',
+  reason: 'Right to erasure request',
+  requestedBy: 'dpo@company.com',
+});
+if (erasure.ok) {
+  console.log(erasure.value.certificateId); // audit-grade certificate
+  console.log(erasure.value.claimsErased);  // count
+}
 
-The governance layer runs whether you configure it or not. The difference between the quickstart and production is explicit configuration -- not a different code path.
+// Protect critical predicates
+limen.governance.protectPredicate({
+  predicatePattern: 'governance.*',
+  requiredRole: 'admin',
+  description: 'Governance claims require admin role',
+});
+
+// SOC 2 audit export
+const audit = limen.governance.exportAudit({
+  fromDate: '2026-01-01T00:00:00Z',
+  toDate: '2026-04-01T00:00:00Z',
+  format: 'json',
+});
+```
 
-Full trust surface with file-and-line evidence: [docs/proof/readiness.md](docs/proof/readiness.md).
+## Security
+
+Limen applies security controls before data reaches storage.
+
+**PII Detection.** Configurable patterns detect and block or redact PII (emails, phone numbers, SSNs, credit cards) before claims are stored. Detections are logged. Sensitivity levels control enforcement.
+
+**Injection Defense.** Claim content is sanitized against prompt injection patterns. SQL injection via FTS5 queries is neutralized. Subject/predicate formats are validated against URI patterns.
+
+**Consent Enforcement.** CRUD for data subject consent records with enforcement on claim assertion. When `security.consent.required` is true, claims about entities are blocked without active consent. Consent status (active, revoked, expired) is computed on read. All mutations produce audit trail entries.
+
+**Classification Filtering.** Claims are classified at assertion time (unrestricted, internal, confidential, restricted, critical). Query and search results are filtered by the requesting agent's clearance level, derived from trust progression (untrusted=0, probationary=1, trusted=2, admin=4).
+
+**Key Rotation.** Atomic re-encryption of all vault entries with a new master key. Transactional — partial failure rolls back completely. Audit trail records every rotation event.
+
+**Poisoning Defense.** The `maxAutoConfidence` ceiling (default 0.7) prevents any programmatic source from laundering high-confidence claims. Only human-verified claims via `evidence_path` grounding can exceed the ceiling.
+
+```typescript
+// Consent management
+limen.consent.register({
+  dataSubjectId: 'user:alice',
+  scope: 'knowledge-storage',
+  basis: 'consent',
+  expiresAt: '2027-01-01T00:00:00Z',
+});
+
+const consent = limen.consent.check('user:alice', 'knowledge-storage');
+// consent.value.status === 'active' | 'revoked' | 'expired'
+```
+
+## Vector Search
+
+Semantic search, hybrid search, and duplicate detection. Requires the optional `sqlite-vec` dependency.
+
+```
+npm install sqlite-vec
+```
+
+```typescript
+import { createLimen } from 'limen-ai';
+
+const limen = await createLimen({
+  vector: {
+    provider: yourEmbeddingProvider,  // (query: string) => Promise<Float32Array>
+    dimensions: 384,
+  },
+});
+
+// Embed pending claims (call after batch inserts)
+await limen.embedPending();
+
+// Semantic search — finds conceptually similar beliefs
+const results = await limen.semanticSearch('food preferences');
+
+// Hybrid search — combines FTS5 keyword + vector similarity
+const hybrid = limen.search('Thai food', { mode: 'hybrid' });
+
+// Duplicate detection before storing
+const dup = await limen.checkDuplicate(
+  'entity:user:alice', 'preference.food', 'loves Thai cuisine'
+);
+if (dup.ok && dup.value.isDuplicate) {
+  console.log(dup.value.similarClaimId);  // existing claim
+  console.log(dup.value.similarity);      // 0.0-1.0
+}
+
+// Embedding statistics
+const stats = limen.embeddingStats();
+if (stats.ok) {
+  console.log(stats.value.totalEmbedded);
+  console.log(stats.value.pendingCount);
+}
+```
+
+Without `sqlite-vec`, `semanticSearch()` falls back to full-text search. The core engine functions identically with or without vector capabilities.
+
+## Self-Healing
+
+When a parent claim is retracted or decays below threshold, derived claims can be automatically retracted in a cascade. This is opt-in.
+
+```typescript
+const limen = await createLimen({
+  selfHealing: {
+    enabled: true,
+    autoRetractThreshold: 0.1,   // retract derived claims when parent drops below this
+    maxCascadeDepth: 5,          // prevent unbounded recursion
+  },
+});
+
+// If "entity:source:data" is retracted...
+limen.forget(sourceClaimId, 'incorrect');
+// ...all claims with derived_from relationships to it
+// are auto-retracted if their effective confidence < 0.1
+```
+
+Disabled by default. Existing applications upgrading to v2.0.0 see no behavior changes unless explicitly configured.
 
 ## Configuration
 
-All fields are optional when calling `createLimen()` with no arguments (zero-config mode).
+All fields optional. `createLimen()` with no arguments runs in zero-config mode.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
@@ -130,12 +315,96 @@ All fields are optional when calling `createLimen()` with no arguments (zero-con
 | `tenancy.isolation` | `'row-level' \| 'database'` | `'row-level'` | Multi-tenant isolation strategy |
 | `cognitive.maxAutoConfidence` | `number` | `0.7` | Confidence ceiling for auto-extracted claims |
 | `autoConflict` | `boolean` | `true` | Structural conflict detection on assertion |
-| `requireRbac` | `boolean` | `false` | Enforce RBAC on all operations |
+| `selfHealing.enabled` | `boolean` | `false` | Auto-retraction cascades (opt-in) |
+| `selfHealing.autoRetractThreshold` | `number` | `0.1` | Effective confidence floor for derived claims |
+| `selfHealing.maxCascadeDepth` | `number` | `5` | Maximum cascade recursion depth |
+| `vector.provider` | `EmbeddingProvider` | `undefined` | Embedding function for semantic search |
+| `vector.dimensions` | `number` | `undefined` | Embedding vector dimensions |
+| `requireRbac` | `boolean` | `false` | Enforce RBAC + classification filtering |
+| `security.consent.required` | `boolean` | `false` | Enforce consent check on claim assertion |
+| `maintenance.retentionEnabled` | `boolean` | `true` | Automatic retention scheduling |
+| `maintenance.retentionIntervalMs` | `number` | `86400000` | Retention check interval (24h default) |
+| `cognitive.autoSuggestConnections` | `boolean` | `true` | Auto-suggest connections on claim assertion |
 | `defaultTimeoutMs` | `number` | `60000` | Chat/infer timeout (ms) |
 | `rateLimiting.apiCallsPerMinute` | `number` | `100` | API rate limit |
 | `failoverPolicy` | `'degrade' \| 'allow-overdraft' \| 'block'` | `'degrade'` | Provider failure behavior |
 | `logger` | `(event) => void` | No-op | Structured logging callback |
 
+## Command Line
+
+Limen includes a full CLI with JSON output for every operation.
+
+```bash
+npm install -g limen-cli
+
+limen init                          # initialize database
+limen remember --subject entity:user:alice --predicate preference.food --value "loves Thai"
+limen recall --subject entity:user:alice
+limen search --query "Thai food"
+limen forget --claimId <id> --reason incorrect
+limen health                        # knowledge health report
+limen consolidate                   # merge, archive, resolve
+limen importance --claimId <id>     # 5-factor importance score
+limen maintenance-retention         # run retention manually
+```
+
+All 36 MCP tools have CLI equivalents. Run `limen --help` for the full list.
+
+## Limen for Claude (MCP)
+
+Add to `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "limen": {
+      "command": "npx",
+      "args": ["-y", "limen-mcp"],
+      "env": {
+        "LIMEN_DATA_DIR": "/path/to/your/data"
+      }
+    }
+  }
+}
+```
+
+36 tools available: `limen_remember`, `limen_recall`, `limen_search`, `limen_forget`, `limen_connect`, `limen_reflect`, `limen_consolidate`, `limen_importance`, `limen_narrative`, `limen_verify`, `limen_suggest_connections`, `limen_replay_verify`, `limen_consent_register`, `limen_consent_check`, `limen_maintenance_retention`, `limen_governance_erasure`, `limen_governance_audit_export`, and more.
+
+## Architecture
+
+```
+API Surface       createLimen(), remember(), recall(), search(), cognitive.*,
+                  governance.*, consent.*, on(), exportData(), importData()
+
+Orchestration     Missions, task graphs, budgets, 16 system calls
+
+Substrate         LLM gateway, transport engine, worker pool
+
+Kernel            SQLite (WAL), audit trail, RBAC, crypto, events
+```
+
+Layers depend downward only. The kernel knows nothing about AI. The API composes everything into a single frozen `Limen` object via `Object.freeze`.
+
+4,000+ tests. 134+ invariants across 3 tiers. 16 system calls. 36 MCP tools. 1 production dependency (`better-sqlite3`). Every state mutation is audited in a hash-chained, append-only trail. RBAC on every operation. AES-256-GCM encryption at rest. Consent enforcement. Classification-filtered retrieval. Automated retention scheduling.
+
+## Trust Surface
+
+What is proven:
+
+- Every invariant in [docs/proof/invariants.md](docs/proof/invariants.md) links to a file and line number in the source. CI verifies these references stay fresh.
+- 16 system calls, each with interface, implementation, and dual-path test coverage (success + rejection). Evidence: [docs/proof/system-calls.md](docs/proof/system-calls.md).
+- Security model with 8 mechanisms and 25 declared non-protections. Evidence: [docs/proof/security-model.md](docs/proof/security-model.md).
+- Failure mode defenses with honest accounting. Evidence: [docs/proof/failure-modes.md](docs/proof/failure-modes.md).
+
+What is not:
+
+- Limen is not a vector database. Semantic search requires an external embedding provider and the optional `sqlite-vec` dependency.
+- Limen does not guarantee real-time performance at scale. SQLite with WAL mode is the foundation — appropriate for single-node deployments with thousands to low millions of claims.
+- The cognitive engine (consolidation, narrative, importance) uses heuristic algorithms, not ML models. Results are deterministic but approximate.
+- Self-healing cascades are opt-in and advisory by design. They retract derived claims but do not rewrite or repair them.
+
+Full trust surface with file-and-line evidence: [docs/proof/readiness.md](docs/proof/readiness.md).
+
 ## Installation Troubleshooting
 
 Limen depends on `better-sqlite3`, which requires native C++ compilation.
@@ -169,17 +438,6 @@ RUN npm install limen-ai
 
 If `npm install` fails with `node-gyp` errors, ensure a C++ toolchain is available. On macOS: `xcode-select --install`. On Linux: `apt install build-essential` or `yum groupinstall "Development Tools"`.
 
-## Architecture
-
-```
-API Surface       createLimen(), remember(), recall(), search(), cognitive.health()
-Orchestration     Missions, task graphs, budgets, 16 system calls
-Substrate         LLM gateway, transport engine, worker pool
-Kernel            SQLite (WAL), audit trail, RBAC, crypto, events
-```
-
-Layers depend downward only. The kernel knows nothing about AI. The API composes everything into a single frozen `Limen` object.
-
 ## License
 
 [Apache License 2.0](LICENSE)

package/dist/api/agents/trust_progression.d.ts

@@ -75,4 +75,24 @@ export type ViolationSeverity = 'low' | 'medium' | 'high' | 'critical';
  *   any on untrusted → null (already at lowest)
  */
 export declare function getDemotionTarget(currentLevel: TrustLevel, severity: ViolationSeverity): TrustLevel | null;
+/**
+ * Map trust levels to classification clearance levels.
+ * Clearance values align with CLASSIFICATION_LEVEL_ORDER in governance_types.ts:
+ *   unrestricted=0, internal=1, confidential=2, restricted=3, critical=4
+ *
+ * untrusted    -> 0 (unrestricted only)
+ * probationary -> 1 (internal and below)
+ * trusted      -> 2 (confidential and below)
+ * admin        -> 4 (all levels including critical)
+ *
+ * This mapping enforces principle of least privilege:
+ * agents must earn trust before accessing sensitive data.
+ */
+export declare const TRUST_TO_CLEARANCE: Readonly<Record<TrustLevel, number>>;
+/**
+ * Get the clearance level for a given trust level.
+ * Returns the maximum classification level the agent can access.
+ * Returns 4 (all) for undefined/null trust (backward compat single-user mode).
+ */
+export declare function getClearanceForTrust(trustLevel: TrustLevel | null | undefined): number;
 //# sourceMappingURL=trust_progression.d.ts.map

package/dist/api/agents/trust_progression.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trust_progression.d.ts","sourceRoot":"","sources":["../../../src/api/agents/trust_progression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAIhE,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,SAAS,GAAG,OAAO,CAAC;AAgB5E;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,UAAU,EACrB,WAAW,EAAE,UAAU,EACvB,SAAS,EAAE,QAAQ,GAAG,OAAO,GAC5B;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA4BpD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,EACtC,aAAa,EAAE,OAAO,GAAG,MAAM,GAC9B;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAQxD;AAID;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,UAAU,EACxB,QAAQ,EAAE,iBAAiB,GAC1B,UAAU,GAAG,IAAI,CAmBnB"}
+{"version":3,"file":"trust_progression.d.ts","sourceRoot":"","sources":["../../../src/api/agents/trust_progression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAIhE,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,SAAS,GAAG,OAAO,CAAC;AAgB5E;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,UAAU,EACrB,WAAW,EAAE,UAAU,EACvB,SAAS,EAAE,QAAQ,GAAG,OAAO,GAC5B;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA4BpD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,EACtC,aAAa,EAAE,OAAO,GAAG,MAAM,GAC9B;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAQxD;AAID;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,UAAU,EACxB,QAAQ,EAAE,iBAAiB,GAC1B,UAAU,GAAG,IAAI,CAmBnB;AAID;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAKnE,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGtF"}

package/dist/api/agents/trust_progression.js

@@ -121,4 +121,34 @@ export function getDemotionTarget(currentLevel, severity) {
     };
     return demotionMap[currentLevel];
 }
+// ─── v3.0.0 EG-03: Trust-to-Clearance Mapping ───
+/**
+ * Map trust levels to classification clearance levels.
+ * Clearance values align with CLASSIFICATION_LEVEL_ORDER in governance_types.ts:
+ *   unrestricted=0, internal=1, confidential=2, restricted=3, critical=4
+ *
+ * untrusted    -> 0 (unrestricted only)
+ * probationary -> 1 (internal and below)
+ * trusted      -> 2 (confidential and below)
+ * admin        -> 4 (all levels including critical)
+ *
+ * This mapping enforces principle of least privilege:
+ * agents must earn trust before accessing sensitive data.
+ */
+export const TRUST_TO_CLEARANCE = {
+    untrusted: 0,
+    probationary: 1,
+    trusted: 2,
+    admin: 4,
+};
+/**
+ * Get the clearance level for a given trust level.
+ * Returns the maximum classification level the agent can access.
+ * Returns 4 (all) for undefined/null trust (backward compat single-user mode).
+ */
+export function getClearanceForTrust(trustLevel) {
+    if (trustLevel === null || trustLevel === undefined)
+        return 4; // full access
+    return TRUST_TO_CLEARANCE[trustLevel] ?? 4;
+}
 //# sourceMappingURL=trust_progression.js.map

package/dist/api/agents/trust_progression.js.map

@@ -1 +1 @@
-{"version":3,"file":"trust_progression.js","sourceRoot":"","sources":["../../../src/api/agents/trust_progression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,wCAAwC;AAExC;;;;GAIG;AACH,MAAM,UAAU,GAA0C;IACxD,SAAS,EAAE,cAAc;IACzB,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,IAAI,EAAE,sCAAsC;CACpD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAmB;IACnD,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAqB,EACrB,WAAuB,EACvB,SAA6B;IAE7B,gCAAgC;IAChC,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,2BAA2B,SAAS,IAAI,EAAE,CAAC;IAC5E,CAAC;IAED,2CAA2C;IAC3C,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IACvC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;IAC9E,CAAC;IAED,IAAI,WAAW,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,+BAA+B,SAAS,QAAQ,WAAW,uBAAuB,QAAQ,yBAAyB;SAC5H,CAAC;IACJ,CAAC;IAED,6BAA6B;IAC7B,IAAI,WAAW,KAAK,OAAO,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;QACrD,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,0CAA0C,SAAS,uCAAuC;SACnG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAsC,EACtC,aAA+B;IAE/B,IAAI,UAAU,IAAI,UAAU,KAAK,aAAa,EAAE,CAAC;QAC/C,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,2DAA2D;SACpE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AASD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,YAAwB,EACxB,QAA2B;IAE3B,iDAAiD;IACjD,IAAI,YAAY,KAAK,WAAW,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wEAAwE;IACxE,IAAI,QAAQ,KAAK,UAAU,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACnD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,sCAAsC;IACtC,MAAM,WAAW,GAAyD;QACxE,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,cAAc;QACvB,YAAY,EAAE,WAAW;KAC1B,CAAC;IAEF,OAAO,WAAW,CAAC,YAAY,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"trust_progression.js","sourceRoot":"","sources":["../../../src/api/agents/trust_progression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,wCAAwC;AAExC;;;;GAIG;AACH,MAAM,UAAU,GAA0C;IACxD,SAAS,EAAE,cAAc;IACzB,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,IAAI,EAAE,sCAAsC;CACpD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAmB;IACnD,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAqB,EACrB,WAAuB,EACvB,SAA6B;IAE7B,gCAAgC;IAChC,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,2BAA2B,SAAS,IAAI,EAAE,CAAC;IAC5E,CAAC;IAED,2CAA2C;IAC3C,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IACvC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;IAC9E,CAAC;IAED,IAAI,WAAW,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,+BAA+B,SAAS,QAAQ,WAAW,uBAAuB,QAAQ,yBAAyB;SAC5H,CAAC;IACJ,CAAC;IAED,6BAA6B;IAC7B,IAAI,WAAW,KAAK,OAAO,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;QACrD,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,0CAA0C,SAAS,uCAAuC;SACnG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAsC,EACtC,aAA+B;IAE/B,IAAI,UAAU,IAAI,UAAU,KAAK,aAAa,EAAE,CAAC;QAC/C,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,2DAA2D;SACpE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AASD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,YAAwB,EACxB,QAA2B;IAE3B,iDAAiD;IACjD,IAAI,YAAY,KAAK,WAAW,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wEAAwE;IACxE,IAAI,QAAQ,KAAK,UAAU,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACnD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,sCAAsC;IACtC,MAAM,WAAW,GAAyD;QACxE,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,cAAc;QACvB,YAAY,EAAE,WAAW;KAC1B,CAAC;IAEF,OAAO,WAAW,CAAC,YAAY,CAAC,CAAC;AACnC,CAAC;AAED,mDAAmD;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAyC;IACtE,SAAS,EAAE,CAAC;IACZ,YAAY,EAAE,CAAC;IACf,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,CAAC;CACT,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAyC;IAC5E,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC,CAAC,cAAc;IAC7E,OAAO,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC"}