iranti 0.3.0 → 0.3.3

package/README.md

@@ -9,11 +9,11 @@
 
 Iranti gives agents persistent, identity-based memory. Facts written by one agent are retrievable by any other agent through exact entity+key lookup. Iranti also supports hybrid search (lexical + vector) when exact keys are unknown. Memory persists across sessions and survives context window limits.
 
-**Repo version:** `0.2.52`  
-**Latest published release:** [`v0.2.51`](https://github.com/nfemmanuel/iranti/releases/tag/v0.2.51)  
+**Repo version:** `0.3.0`  
 Published packages:
-- `iranti@0.2.51`
-- `@iranti/sdk@0.2.51`
+- npm `iranti@0.3.0`
+- npm `@iranti/sdk@0.3.0`
+- PyPI `iranti==0.3.0`
 
 ---
 
@@ -53,27 +53,29 @@ Vector databases answer "what's similar to X?" Iranti answers "what do we know a
 
 ## Benchmark Summary
 
-Iranti now has current rerun evidence across exact retrieval, process continuity, upgrade durability, relationships, bounded conflict handling, and bounded recovery behavior. The current picture is stronger and narrower than the early validation story: exact, durable, shared memory is validated; broad semantic-memory and autonomous-recovery claims still need explicit limits.
+Iranti now has current rerun evidence across exact retrieval, process continuity, upgrade durability, relationships, bounded conflict handling, and bounded recovery behavior. The current picture is stronger and narrower than the early validation story: exact, durable, shared memory is validated; broad semantic-memory and autonomous-recovery claims still need explicit limits.
 
 ### Confirmed Strengths
 
-- **Exact lookup (`iranti_query`)**: The current installed-local `0.2.52` rerun still scored `10/10` on the canonical B1 exact-retrieval arm.
-- **Persistence across sessions and processes**: Facts survive context-window loss and genuine process boundaries, with current reruns and validation passes covering process-isolated reads plus cross-process invalidation.
-- **Upgrade durability**: A fresh continuity chain now passes across public npm `0.2.49 -> 0.2.50 -> 0.2.51` plus a final installed-local `0.2.52` hop.
+- **Exact lookup (`iranti_query`)**: The prepublish candidate for the current `0.3.0` line still scored `10/10` on the canonical B1 exact-retrieval arm.
+- **Persistence across sessions and processes**: Facts survive context-window loss and genuine process boundaries, with current reruns and validation passes covering process-isolated reads plus cross-process invalidation.
+- **Upgrade durability**: A fresh continuity chain now passes across public npm `0.2.49 -> 0.2.50 -> 0.2.51` plus a final prepublish candidate hop on the `0.3.0` line.
 - **Conflict handling**: Reliable when confidence differentials are large and explicit.
-- **Relationship traversal and multi-agent coordination**: Relationship writes plus one-hop/deep traversal work, and agents can share memory across genuine subprocess boundaries with zero shared conversational context.
+- **Relationship traversal and multi-agent coordination**: Relationship writes plus one-hop/deep traversal work, and agents can share memory across genuine subprocess boundaries with zero shared conversational context.
 - **Provenance on writes**: Write-side attribution through stored source metadata is working and benchmark-confirmed.
-- **Ingest**: Prose extraction is accurate on clean entities in the bounded rerun surfaces already documented.
-- **Observe with hints / explicit recovery**: `iranti_observe` with hints and explicit query-based recovery are meaningfully useful today.
-
-Recent fixes since the last rerun:
-- **Search now bridges semantic hits across relationships for filtered retrieval.** A strong incident or issue hit can now propagate back onto the owning filtered entity over up to two hops, so filtered project search no longer depends on direct lexical overlap alone.
-- **`iranti_attend` now safe-defaults parse failures toward memory on non-greeting turns.** Terse prompts such as `help`, `why?`, or `how?` no longer silently fall through to `classification_parse_failed_default_false`.
-- **Hybrid search now indexes entity addresses directly.** Addressed queries such as `project/<id> status` no longer rely on value-summary overlap alone.
-
-### Current Limits
-
+- **Ingest**: Prose extraction is accurate on clean entities in the bounded rerun surfaces already documented.
+- **Observe with hints / explicit recovery**: `iranti_observe` with hints and explicit query-based recovery are meaningfully useful today.
+- **Protocol enforcement turn-gate**: Strict turn-cycle enforcement (handshake → attend → discover → post-response) is validated by focused route and MCP regression tests. In `strict` mode, KB discovery routes return HTTP 428 with a structured violation payload before an agent that skipped attend can silently read stale memory. Injected facts now include a `lastUpdated` timestamp so the calling agent can judge freshness at the point of injection.
+
+Recent fixes since the last rerun:
+- **Search now bridges semantic hits across relationships for filtered retrieval.** A strong incident or issue hit can now propagate back onto the owning filtered entity over up to two hops, so filtered project search no longer depends on direct lexical overlap alone.
+- **`iranti_attend` now safe-defaults parse failures toward memory on non-greeting turns.** Terse prompts such as `help`, `why?`, or `how?` no longer silently fall through to `classification_parse_failed_default_false`.
+- **Hybrid search now indexes entity addresses directly.** Addressed queries such as `project/<id> status` no longer rely on value-summary overlap alone.
+
+### Current Limits
+
 - **Upgrade durability is now test-covered.** The `v0.2.21` upgrade reinitialized the instance under test — a one-time operator incident, not a systemic design flaw. All Prisma migrations are additive (no DROP or TRUNCATE); Staff Namespace seeding is guarded by `isSeeded()`; `seed-codebase.ts` upserts to `codebase/*` entities only. A KB preservation test in `tests/runtime-lifecycle/run_setup_upgrade_tests.ts` now confirms user KB data written before a `setup` re-run survives intact.
+- **Project learning is now only a bounded bind-time snapshot.** When you bind a project, Iranti derives a stable `IRANTI_CODEBASE_ENTITY` and writes a small snapshot from authoritative files such as `package.json`, `README.md`, `tsconfig.json`, `pyproject.toml`, `prisma/schema.prisma`, and common source directories. It does not yet crawl the repo continuously or build autonomous whole-project understanding.
 - **Relationship and provenance reflection surfaces remain partially permission-gated in benchmark sessions.** The rerun did not prove `iranti_relate`, `iranti_related`, `iranti_related_deep`, or `iranti_who_knows` end-to-end under the benchmark session policy.
 
 ### Practical Position
@@ -81,9 +83,10 @@ Recent fixes since the last rerun:
 Iranti is strongest today as **structured memory infrastructure for multi-agent systems**:
 - exact entity/key lookup
 - durable shared memory
-- provenance-aware writes
+- provenance-aware writes with source attribution and freshness timestamps
 - conflict-aware storage
 - session-aware recovery
+- protocol-enforced turn discipline for trustworthy injection (opt-in strict mode)
 
 It should not yet be described as a fully general semantic-memory, semantic-search, or autonomous-memory-injection system.
 
@@ -468,6 +471,7 @@ iranti project init . --instance local --agent-id chatbot_main
 ```
 
 This writes `.env.iranti` in the project with the correct `IRANTI_URL`, `IRANTI_API_KEY`, and default agent identity.
+It also writes a derived `IRANTI_CODEBASE_ENTITY` and a bounded initial project snapshot for that bound repo.
 
 Later changes use the same surface:
 
@@ -608,19 +612,19 @@ for item in matches:
     print(item["entity"], item["key"], item["score"])
 ```
 
-### Context Persistence (attend)
-
-`handshake()` establishes the session contract. Discovery surfaces such as `query`, `search`, `get_related`, and `who_knows` are now fail-closed until the host has run `handshake()` for the session and `attend()` for the current turn. Starting a new `attend(phase="pre-response")` turn without first closing the previous one with `attend(phase="post-response")` is now blocked as a protocol violation, and `inspectSession()` / `listSessions()` expose structured lifecycle compliance state (`healthy`, `degraded`, `non_compliant`) so hosts and operators can see when breadcrumb discipline is slipping.
-
-```python
-# Before each LLM call, let Attendant decide if memory is needed
-result = client.attend(
-    agent_id="research_agent_001",
-    latest_message="What's Jane Smith's current affiliation?",
-    current_context="User: What's Jane Smith's current affiliation?\nAssistant: Let me check...",
-    max_facts=5,
-    phase="pre-response"
-)
+### Context Persistence (attend)
+
+`handshake()` establishes the session contract. Discovery surfaces such as `query`, `search`, `get_related`, and `who_knows` are now fail-closed until the host has run `handshake()` for the session and `attend()` for the current turn. Starting a new `attend(phase="pre-response")` turn without first closing the previous one with `attend(phase="post-response")` is now blocked as a protocol violation, and `inspectSession()` / `listSessions()` expose structured lifecycle compliance state (`healthy`, `degraded`, `non_compliant`) so hosts and operators can see when breadcrumb discipline is slipping.
+
+```python
+# Before each LLM call, let Attendant decide if memory is needed
+result = client.attend(
+    agent_id="research_agent_001",
+    latest_message="What's Jane Smith's current affiliation?",
+    current_context="User: What's Jane Smith's current affiliation?\nAssistant: Let me check...",
+    max_facts=5,
+    phase="pre-response"
+)
 
 if result["shouldInject"]:
     for fact in result['facts']:
@@ -731,11 +735,11 @@ middleware.after_receive(
 )
 ```
 
-**How it works**:
-1. `before_send()` calls `attend()` with conversation context
-2. Forgotten facts are prepended as `[MEMORY: ...]`
-3. `after_receive()` extracts new facts and saves them (best-effort)
-4. If the host skips `handshake()` or `attend()`, discovery calls block instead of returning warn-only metadata
+**How it works**:
+1. `before_send()` calls `attend()` with conversation context
+2. Forgotten facts are prepended as `[MEMORY: ...]`
+3. `after_receive()` extracts new facts and saves them (best-effort)
+4. If the host skips `handshake()` or `attend()`, discovery calls block instead of returning warn-only metadata
 
 **Note**: Browser extensions are blocked by ChatGPT and Claude's Content Security Policy. Use API-based middleware instead.
 
@@ -762,10 +766,10 @@ Express server on port 3001 with endpoints:
 - `POST /kb/write` - Write atomic fact
 - `POST /kb/ingest` - Ingest raw text for one entity, auto-chunk into facts with per-fact confidence and per-fact write outcomes
 - `GET /kb/query/:entityType/:entityId/:key` - Query specific fact
-- `GET /kb/query/:entityType/:entityId` - Query all facts for entity
-- `GET /kb/search` - Hybrid search across facts
-- `POST /memory/attend` - Decide whether to inject memory for this turn and unlock one discovery step for the current turn
-- `POST /memory/observe` - Context persistence (inject missing facts)
+- `GET /kb/query/:entityType/:entityId` - Query all facts for entity
+- `GET /kb/search` - Hybrid search across facts
+- `POST /memory/attend` - Decide whether to inject memory for this turn and unlock one discovery step for the current turn
+- `POST /memory/observe` - Context persistence (inject missing facts)
 - `POST /memory/handshake` - Working memory brief for agent session
 - `GET /memory/ledger` - Read structured session ledger events from `staff_events`
 - `GET /memory/sessions` - List persisted operator-visible session checkpoints across agents, with optional operator filters/sorting
@@ -774,8 +778,8 @@ Express server on port 3001 with endpoints:
 - `GET /kb/related/:entityType/:entityId` - Get related entities
 - `POST /agents/register` - Register agent in registry
 
-All endpoints require `X-Iranti-Key` header for authentication.
-Discovery endpoints return `428 Precondition Required` when a host skips the required session `handshake` or current-turn `attend`.
+All endpoints require `X-Iranti-Key` header for authentication.
+Discovery endpoints return `428 Precondition Required` when a host skips the required session `handshake` or current-turn `attend`.
 
 ---
 

package/dist/scripts/claude-code-memory-hook.js

@@ -11,6 +11,8 @@ const runtimeEnv_1 = require("../src/lib/runtimeEnv");
 const staffEventRegistry_1 = require("../src/lib/staffEventRegistry");
 const client_1 = require("../src/library/client");
 const autoRemember_1 = require("../src/lib/autoRemember");
+const assistantCheckpoint_1 = require("../src/lib/assistantCheckpoint");
+const hostMemoryFormatting_1 = require("../src/lib/hostMemoryFormatting");
 const MEMORY_NEED_POSITIVE_PATTERNS = [
     /\bwhat(?:'s| is| was)?\s+my\b/i,
     /\bdo you remember\b/i,
@@ -41,7 +43,7 @@ function printHelp() {
         '',
         'Reads Claude Code hook JSON from stdin and returns hookSpecificOutput.additionalContext on stdout.',
         'This helper retrieves working memory; durable KB writes still require explicit iranti_write/ingest calls.',
-        'Set IRANTI_AUTO_REMEMBER=true to auto-save narrow personal facts to IRANTI_PERSONAL_MEMORY_ENTITY/user/main, project summaries to IRANTI_MEMORY_ENTITY, and shared checkpoint breadcrumbs for resumable work.',
+        'Set IRANTI_AUTO_REMEMBER=true to auto-save prompt-side personal/project facts. Assistant-response continuity facts and shared checkpoints are captured on Stop regardless.',
     ].join('\n'));
 }
 function parseArgs(argv) {
@@ -229,19 +231,29 @@ function getMaxFacts() {
     return Math.min(12, Math.trunc(raw));
 }
 function formatSessionContext(facts, cwd) {
-    const limited = facts.slice(0, getMaxFacts());
+    const limited = (0, hostMemoryFormatting_1.assignStructuredFactIds)(facts.slice(0, getMaxFacts()).map((fact) => ({
+        ...fact,
+        entityKey: `${fact.entity}/${fact.key}`,
+    })));
     const lines = [
         '[Iranti Session Memory]',
         `Project: ${path_1.default.basename(cwd)}`,
         'REQUIRED: Call mcp__iranti__iranti_handshake before responding to the first user message.',
-        'REQUIRED: Call mcp__iranti__iranti_attend before every subsequent turn.',
+        'REQUIRED: Call mcp__iranti__iranti_attend(phase=\'pre-response\') before every reply and before factual discovery.',
+        'REQUIRED: After every response, call mcp__iranti__iranti_attend(phase=\'post-response\').',
+        'REQUIRED: Prefer injected Iranti facts before re-inferring project state.',
+        'REQUIRED: Call mcp__iranti__iranti_write after every file edit, confirmed finding, system state discovery, and subagent completion — write what changed, why, and what it means.',
     ];
-    if (limited.length > 0) {
-        lines.push('Relevant memory:');
-        for (const fact of limited) {
-            lines.push(`- ${fact.entity}/${fact.key}: ${fact.summary}`);
-        }
-    }
+    const block = (0, hostMemoryFormatting_1.formatStructuredFactBlock)(limited, {
+        title: 'Iranti Session Facts',
+        introLines: [
+            'Use these loaded facts as the starting working-memory frame for this session.',
+            'Prefer them before re-inferring project state.',
+            'Fact IDs are stable only within this block.',
+        ],
+    });
+    if (block)
+        lines.push(block);
     return lines.join('\n');
 }
 function formatPreCompactContext() {
@@ -270,154 +282,22 @@ function extractSelfMemoryQueryKey(prompt) {
 function formatPromptContext(facts, prompt) {
     if (facts.length === 0)
         return '';
-    const lines = ['[Iranti Retrieved Memory]'];
+    const structuredFacts = (0, hostMemoryFormatting_1.assignStructuredFactIds)(facts.map((fact) => ({
+        ...fact,
+        entityKey: `${fact.entity}/${fact.key}`,
+    })));
+    const lines = [];
     const targetKey = prompt ? extractSelfMemoryQueryKey(prompt) : null;
     if (targetKey) {
-        const answerCandidate = facts.find((fact) => (0, autoRemember_1.canonicalizeMemoryKey)(fact.key) === targetKey);
+        const answerCandidate = structuredFacts.find((fact) => (0, autoRemember_1.canonicalizeMemoryKey)(fact.entityKey.split('/').slice(2).join('/')) === targetKey);
         if (answerCandidate) {
-            lines.push(`Direct answer: ${answerCandidate.summary}.`);
-            lines.push('Use the direct answer above when it fully answers the user question.');
+            lines.push(`[Iranti Direct Answer]`);
+            lines.push(`Use ${answerCandidate.factId} directly if it fully answers the user question: ${answerCandidate.summary}.`);
         }
     }
-    for (const fact of facts) {
-        lines.push(`- ${fact.entity}/${fact.key}: ${fact.summary}`);
-    }
+    lines.push((0, hostMemoryFormatting_1.formatStructuredFactBlock)(structuredFacts, { title: 'Iranti Retrieved Memory' }));
     return lines.join('\n');
 }
-function readTextField(value, preferredKey) {
-    if (typeof value !== 'object' || value === null)
-        return undefined;
-    const record = value;
-    const raw = record[preferredKey];
-    return typeof raw === 'string' && raw.trim() ? raw.trim() : undefined;
-}
-function readItems(value) {
-    if (typeof value !== 'object' || value === null)
-        return [];
-    const record = value;
-    const items = Array.isArray(record.items) ? record.items : [];
-    return items.map((item) => String(item ?? '').trim()).filter(Boolean);
-}
-function readFileChangeOutputs(value) {
-    if (typeof value !== 'object' || value === null)
-        return [];
-    const record = value;
-    const items = Array.isArray(record.items) ? record.items : [];
-    return items.map((item) => {
-        if (typeof item !== 'object' || item === null)
-            return '';
-        const change = item;
-        const action = String(change.action ?? 'updated').trim();
-        const targetPath = String(change.path ?? '').trim();
-        const toPath = String(change.toPath ?? '').trim();
-        if (!targetPath)
-            return '';
-        return toPath ? `${action} ${targetPath} -> ${toPath}` : `${action} ${targetPath}`;
-    }).filter(Boolean);
-}
-function readCheckpointActions(value) {
-    if (typeof value !== 'object' || value === null)
-        return [];
-    const record = value;
-    const items = Array.isArray(record.items) ? record.items : [];
-    return items
-        .map((item) => {
-        if (typeof item !== 'object' || item === null)
-            return null;
-        const action = item;
-        const summary = String(action.summary ?? '').trim();
-        if (!summary)
-            return null;
-        const kind = String(action.kind ?? 'action').trim() || 'action';
-        return {
-            kind,
-            summary,
-            ...(typeof action.status === 'string' && action.status.trim() ? { status: action.status.trim() } : {}),
-            ...(typeof action.target === 'string' && action.target.trim() ? { target: action.target.trim() } : {}),
-            ...(typeof action.detail === 'string' && action.detail.trim() ? { detail: action.detail.trim() } : {}),
-        };
-    })
-        .filter((item) => Boolean(item));
-}
-function readActionOutputs(value) {
-    if (typeof value !== 'object' || value === null)
-        return [];
-    const record = value;
-    const items = Array.isArray(record.items) ? record.items : [];
-    return items.map((item) => {
-        if (typeof item !== 'object' || item === null)
-            return '';
-        const action = item;
-        const kind = String(action.kind ?? 'action').trim() || 'action';
-        const summary = String(action.summary ?? '').trim();
-        const status = String(action.status ?? '').trim();
-        if (!summary)
-            return '';
-        return status ? `[${status}] ${kind}: ${summary}` : `${kind}: ${summary}`;
-    }).filter(Boolean);
-}
-function extractHookCheckpointPayload(response) {
-    const facts = (0, autoRemember_1.extractExplicitAssistantMemory)(response).filter((fact) => fact.scope === 'project');
-    if (facts.length === 0) {
-        return null;
-    }
-    const checkpoint = {};
-    const outputs = [];
-    for (const fact of facts) {
-        if (fact.key === 'current_step') {
-            checkpoint.currentStep = readTextField(fact.value, 'text');
-            continue;
-        }
-        if (fact.key === 'next_step') {
-            checkpoint.nextStep = readTextField(fact.value, 'instruction') ?? readTextField(fact.value, 'text');
-            continue;
-        }
-        if (fact.key === 'open_risks') {
-            checkpoint.openRisks = readItems(fact.value);
-            continue;
-        }
-        if (fact.key === 'important_artifacts') {
-            outputs.push(...readItems(fact.value));
-            continue;
-        }
-        if (fact.key === 'recent_file_changes') {
-            const fileChanges = typeof fact.value === 'object' && fact.value !== null && Array.isArray(fact.value.items)
-                ? fact.value.items
-                    .filter((item) => item && typeof item === 'object')
-                    .map((item) => ({
-                    action: String(item.action ?? 'updated').trim() || 'updated',
-                    path: String(item.path ?? '').trim(),
-                    ...(typeof item.toPath === 'string' && item.toPath.trim() ? { toPath: String(item.toPath).trim() } : {}),
-                    ...(typeof item.purpose === 'string' && item.purpose.trim() ? { purpose: String(item.purpose).trim() } : {}),
-                }))
-                    .filter((item) => item.path)
-                : [];
-            if (fileChanges.length > 0) {
-                checkpoint.fileChanges = [...(checkpoint.fileChanges ?? []), ...fileChanges];
-            }
-            outputs.push(...readFileChangeOutputs(fact.value));
-            continue;
-        }
-        if (fact.key === 'recent_actions') {
-            const actions = readCheckpointActions(fact.value);
-            if (actions.length > 0) {
-                checkpoint.actions = [...(checkpoint.actions ?? []), ...actions];
-            }
-            outputs.push(...readActionOutputs(fact.value));
-        }
-    }
-    if (outputs.length > 0) {
-        checkpoint.recentOutputs = outputs;
-    }
-    return checkpoint.currentStep
-        || checkpoint.nextStep
-        || (checkpoint.openRisks && checkpoint.openRisks.length > 0)
-        || (checkpoint.recentOutputs && checkpoint.recentOutputs.length > 0)
-        || (checkpoint.actions && checkpoint.actions.length > 0)
-        || (checkpoint.fileChanges && checkpoint.fileChanges.length > 0)
-        ? checkpoint
-        : null;
-}
 function emitHookContext(event, additionalContext) {
     const payload = {
         hookSpecificOutput: {
@@ -523,8 +403,8 @@ async function buildHookAdditionalContext(options) {
     }
     if (event === 'Stop') {
         const response = getLastAssistantMessage(payload);
-        if (response && (0, autoRemember_1.isAutoRememberEnabled)()) {
-            await (0, autoRemember_1.autoRememberAssistantFacts)({
+        if (response) {
+            await (0, autoRemember_1.rememberAssistantResponseFacts)({
                 iranti,
                 response,
                 agent,
@@ -534,7 +414,7 @@ async function buildHookAdditionalContext(options) {
                     host: 'claude_code',
                 },
             });
-            const checkpoint = extractHookCheckpointPayload(response);
+            const checkpoint = (0, assistantCheckpoint_1.extractAssistantCheckpointPayload)(response);
             const projectEntity = (0, autoRemember_1.getProjectMemoryEntity)();
             if (checkpoint && projectEntity && typeof iranti.checkpoint === 'function') {
                 await iranti.checkpoint({
@@ -547,6 +427,14 @@ async function buildHookAdditionalContext(options) {
                     },
                 });
             }
+            await iranti.attend({
+                agent,
+                latestMessage: response,
+                currentContext: response,
+                entityHints,
+                maxFacts: getMaxFacts(),
+                phase: 'post-response',
+            });
         }
         return '';
     }
@@ -575,6 +463,7 @@ async function buildHookAdditionalContext(options) {
         currentContext: buildCurrentContext(payload, prompt),
         entityHints,
         maxFacts: getMaxFacts(),
+        phase: 'pre-response',
     });
     const facts = attend.facts.map((fact) => ({
         entity: fact.entityKey.split('/').slice(0, 2).join('/'),

package/dist/scripts/codex-setup.js

@@ -225,7 +225,7 @@ function buildCodexAgentsBlock() {
         '- Call `mcp__iranti__iranti_checkpoint` at natural pauses, before stepping away from long work, when interrupted, and when completing a useful slice.',
         '- When useful actions happen, record them in the checkpoint `actions` field so later sessions can see important commands, tests, searches, validations, and decisions without rerunning them blindly.',
         '- Do not treat durable writes as a substitute for checkpoints. A checkpoint not written means the next session has to reconstruct state.',
-        '- Under-logged runs are non-compliant for this repo. When applicable, leave structured breadcrumbs for what you found, what worked, what failed, what changed, and what happens next instead of only a broad summary.',
+        '- Under-logged runs are non-compliant for this repo. When applicable, call iranti_write with what you found, what worked, what failed, what changed, and what happens next — not a broad summary, but specific durable facts.',
         '',
         '## Host setup check',
         '- If this block was missing at session start, rerun `iranti codex-setup` from the bound project root.',