iranti 0.1.1 → 0.1.3

package/README.md

@@ -178,24 +178,24 @@ Release guide: [`docs/guides/releasing.md`](docs/guides/releasing.md)
 Iranti ships a local stdio MCP server for Claude Code and other MCP clients:
 
 ```bash
-npm run build
-node dist/scripts/iranti-mcp.js
+iranti mcp
 ```
 
-Use it with a project-local `.mcp.json`, and optionally add the Claude Code hook helper for `SessionStart` and `UserPromptSubmit`.
+Use it with a project-local `.mcp.json`, and optionally add `iranti claude-hook` for `SessionStart` and `UserPromptSubmit`.
 
 Guide: [`docs/guides/claude-code.md`](docs/guides/claude-code.md)
 
 ### Codex via MCP
 
-Codex uses a global MCP registry rather than a project-local `.mcp.json`. Register Iranti once, then launch Codex in this repo so `AGENTS.md` applies:
+Codex uses a global MCP registry rather than a project-local `.mcp.json`. Register Iranti once, then launch Codex in the bound project so `.env.iranti` is in scope:
 
 ```bash
-npm run build
-npm run codex:setup
-npm run codex:run
+iranti codex-setup
+codex -C /path/to/your/project
 ```
 
+When `iranti codex-setup` is run from a project directory, it automatically captures that project's `.env.iranti` as `IRANTI_PROJECT_ENV` so Codex resolves the correct Iranti instance consistently.
+
 Guide: [`docs/guides/codex.md`](docs/guides/codex.md)
 
 ---

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

@@ -6,6 +6,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 require("dotenv/config");
 const path_1 = __importDefault(require("path"));
 const sdk_1 = require("../src/sdk");
+const runtimeEnv_1 = require("../src/lib/runtimeEnv");
+const MEMORY_NEED_POSITIVE_PATTERNS = [
+    /\bwhat(?:'s| is| was)?\s+my\b/i,
+    /\bdo you remember\b/i,
+    /\bremind me\b/i,
+    /\bmy\s+(?:favorite|favourite|name|email|phone|address|city|country|movie|snack|color|colour)\b/i,
+    /\bwe decided\b/i,
+    /\bearlier\b/i,
+    /\bprevious(?:ly)?\b/i,
+    /\bagain\b/i,
+];
+const MEMORY_NEED_NEGATIVE_PATTERNS = [
+    /^\s*(hi|hello|hey|yo|sup|good (?:morning|afternoon|evening))\b[!.?\s]*$/i,
+    /^\s*(thanks|thank you|cool|great|nice)\b[!.?\s]*$/i,
+];
 function printHelp() {
     console.log([
         'Claude Code -> Iranti hook helper',
@@ -14,6 +29,11 @@ function printHelp() {
         '  ts-node scripts/claude-code-memory-hook.ts --event SessionStart',
         '  ts-node scripts/claude-code-memory-hook.ts --event UserPromptSubmit',
         '',
+        'Optional flags:',
+        '  --project-env <path>   Explicit .env.iranti path',
+        '  --instance-env <path>  Explicit instance env path',
+        '  --env-file <path>      Explicit base .env path',
+        '',
         'Reads Claude Code hook JSON from stdin and returns hookSpecificOutput.additionalContext on stdout.',
     ].join('\n'));
 }
@@ -77,6 +97,9 @@ function getDefaultAgentId(payload) {
     const explicit = process.env.IRANTI_CLAUDE_AGENT_ID?.trim();
     if (explicit)
         return explicit;
+    const projectBindingAgent = process.env.IRANTI_AGENT_ID?.trim();
+    if (projectBindingAgent)
+        return projectBindingAgent;
     const base = path_1.default.basename(getCwd(payload));
     return `claude_code_${slugify(base || 'project')}`;
 }
@@ -85,6 +108,10 @@ function getEntityHints(payload) {
     const cwd = getCwd(payload);
     const projectHint = `project/${slugify(path_1.default.basename(cwd) || 'project')}`;
     out.add(projectHint);
+    const memoryEntity = process.env.IRANTI_MEMORY_ENTITY?.trim();
+    if (memoryEntity) {
+        out.add(memoryEntity);
+    }
     const envHints = (process.env.IRANTI_CLAUDE_ENTITY_HINTS ?? '')
         .split(',')
         .map((value) => value.trim())
@@ -105,7 +132,17 @@ async function ensureHookAgent(iranti, payload) {
     return agentId;
 }
 function getPrompt(payload) {
-    return typeof payload.prompt === 'string' ? payload.prompt.trim() : '';
+    const candidates = [
+        payload.prompt,
+        payload.message,
+        payload.text,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate.trim()) {
+            return candidate.trim();
+        }
+    }
+    return '';
 }
 function getMaxFacts() {
     const raw = Number(process.env.IRANTI_CLAUDE_MAX_FACTS ?? 6);
@@ -113,41 +150,26 @@ function getMaxFacts() {
         return 6;
     return Math.min(12, Math.trunc(raw));
 }
-function formatHandshakeContext(brief, cwd) {
-    const facts = Array.isArray(brief?.workingMemory) ? brief.workingMemory.slice(0, getMaxFacts()) : [];
+function formatSessionContext(facts, cwd) {
+    const limited = facts.slice(0, getMaxFacts());
     const lines = [
         '[Iranti Session Memory]',
         `Project: ${path_1.default.basename(cwd)}`,
     ];
-    if (typeof brief?.inferredTaskType === 'string' && brief.inferredTaskType) {
-        lines.push(`Task type: ${brief.inferredTaskType}`);
-    }
-    if (facts.length > 0) {
+    if (limited.length > 0) {
         lines.push('Relevant memory:');
-        for (const fact of facts) {
-            const label = typeof fact?.entityKey === 'string' ? fact.entityKey : `${fact?.entityType ?? 'entity'}/${fact?.entityId ?? 'unknown'}`;
-            const summary = typeof fact?.summary === 'string' ? fact.summary : fact?.valueSummary;
-            if (!summary)
-                continue;
-            lines.push(`- ${label}: ${summary}`);
+        for (const fact of limited) {
+            lines.push(`- ${fact.entity}/${fact.key}: ${fact.summary}`);
         }
     }
     return lines.join('\n');
 }
-function formatAttendContext(attend) {
-    const facts = Array.isArray(attend?.facts) ? attend.facts.slice(0, getMaxFacts()) : [];
-    if (!attend?.shouldInject || facts.length === 0)
+function formatPromptContext(facts) {
+    if (facts.length === 0)
         return '';
     const lines = ['[Iranti Retrieved Memory]'];
-    if (typeof attend?.reason === 'string' && attend.reason) {
-        lines.push(`Reason: ${attend.reason}`);
-    }
     for (const fact of facts) {
-        const label = typeof fact?.entityKey === 'string' ? fact.entityKey : `${fact?.entityType ?? 'entity'}/${fact?.entityId ?? 'unknown'}`;
-        const summary = typeof fact?.summary === 'string' ? fact.summary : fact?.valueSummary;
-        if (!summary)
-            continue;
-        lines.push(`- ${label}: ${summary}`);
+        lines.push(`- ${fact.entity}/${fact.key}: ${fact.summary}`);
     }
     return lines.join('\n');
 }
@@ -160,6 +182,98 @@ function emitHookContext(event, additionalContext) {
     };
     process.stdout.write(`${JSON.stringify(payload)}\n`);
 }
+function shouldFetchMemory(prompt) {
+    const normalized = prompt.trim();
+    if (!normalized)
+        return false;
+    if (MEMORY_NEED_NEGATIVE_PATTERNS.some((pattern) => pattern.test(normalized))) {
+        return false;
+    }
+    if (MEMORY_NEED_POSITIVE_PATTERNS.some((pattern) => pattern.test(normalized))) {
+        return true;
+    }
+    if (/\b(my|our|we)\b/i.test(normalized)) {
+        return true;
+    }
+    return normalized.includes('/');
+}
+function dedupeFacts(facts) {
+    const byKey = new Map();
+    for (const fact of facts) {
+        const identity = `${fact.entity}/${fact.key}`;
+        const existing = byKey.get(identity);
+        if (!existing || fact.confidence > existing.confidence) {
+            byKey.set(identity, fact);
+        }
+    }
+    return Array.from(byKey.values())
+        .sort((a, b) => b.confidence - a.confidence || a.entity.localeCompare(b.entity) || a.key.localeCompare(b.key))
+        .slice(0, getMaxFacts());
+}
+async function loadAttendantStateFacts(iranti, agent) {
+    const state = await iranti.query(`agent/${agent}`, 'attendant_state');
+    if (!state.found || !state.value || typeof state.value !== 'object') {
+        return [];
+    }
+    const workingMemory = Array.isArray(state.value.workingMemory)
+        ? state.value.workingMemory
+        : [];
+    return workingMemory.flatMap((entry) => {
+        const entityKey = typeof entry.entityKey === 'string' ? entry.entityKey.trim() : '';
+        const summary = typeof entry.summary === 'string' ? entry.summary.trim() : '';
+        if (!entityKey || !summary)
+            return [];
+        const segments = entityKey.split('/');
+        if (segments.length < 3)
+            return [];
+        return [{
+                entity: `${segments[0]}/${segments[1]}`,
+                key: segments.slice(2).join('/'),
+                summary,
+                confidence: typeof entry.confidence === 'number' ? entry.confidence : 0,
+                source: typeof entry.source === 'string' ? entry.source : 'attendant',
+            }];
+    });
+}
+async function loadEntityFacts(iranti, entities) {
+    const out = [];
+    for (const entity of entities) {
+        const trimmed = entity.trim();
+        if (!trimmed)
+            continue;
+        const entries = await iranti.queryAll(trimmed).catch(() => []);
+        for (const entry of entries) {
+            out.push({
+                entity: trimmed,
+                key: entry.key,
+                summary: entry.summary,
+                confidence: entry.confidence,
+                source: entry.source,
+            });
+        }
+    }
+    return out;
+}
+async function searchPromptFacts(iranti, prompt, entityHints) {
+    if (!prompt.trim())
+        return [];
+    const results = await iranti.search({
+        query: prompt,
+        limit: getMaxFacts(),
+        minScore: Number(process.env.IRANTI_CLAUDE_MIN_SEARCH_SCORE ?? 0.05),
+    }).catch(() => []);
+    const searched = results.map((result) => ({
+        entity: result.entity,
+        key: result.key,
+        summary: result.summary,
+        confidence: result.confidence,
+        source: result.source,
+    }));
+    if (searched.length > 0) {
+        return searched;
+    }
+    return loadEntityFacts(iranti, entityHints);
+}
 async function main() {
     if (process.argv.includes('--help') || process.argv.includes('-h')) {
         printHelp();
@@ -171,6 +285,12 @@ async function main() {
         throw new Error('--event must be SessionStart or UserPromptSubmit');
     }
     const payload = parsePayload(await readStdin());
+    (0, runtimeEnv_1.loadRuntimeEnv)({
+        payloadCwd: getCwd(payload),
+        projectEnvFile: args['project-env'],
+        instanceEnvFile: args['instance-env'],
+        explicitEnvFile: args['env-file'],
+    });
     const cwd = getCwd(payload);
     const iranti = new sdk_1.Iranti({
         connectionString: requireConnectionString(),
@@ -179,30 +299,27 @@ async function main() {
     const agent = await ensureHookAgent(iranti, payload);
     const entityHints = getEntityHints(payload);
     if (event === 'SessionStart') {
-        const task = process.env.IRANTI_CLAUDE_SESSION_TASK?.trim()
-            || `Claude Code session in ${path_1.default.basename(cwd)}`;
-        const brief = await iranti.handshake({
-            agent,
-            task,
-            recentMessages: [],
-        });
-        emitHookContext(event, formatHandshakeContext(brief, cwd));
-        return;
+        const persistedFacts = await loadAttendantStateFacts(iranti, agent);
+        const directFacts = persistedFacts.length > 0
+            ? persistedFacts
+            : await loadEntityFacts(iranti, entityHints);
+        emitHookContext(event, formatSessionContext(dedupeFacts(directFacts), cwd));
+        process.exit(0);
     }
     const prompt = getPrompt(payload);
-    if (!prompt)
-        return;
-    const attend = await iranti.attend({
-        agent,
-        latestMessage: prompt,
-        currentContext: prompt,
-        entityHints,
-        maxFacts: getMaxFacts(),
-    });
-    const context = formatAttendContext(attend);
-    if (!context)
-        return;
+    if (!prompt) {
+        process.exit(0);
+    }
+    if (!shouldFetchMemory(prompt)) {
+        process.exit(0);
+    }
+    const facts = await searchPromptFacts(iranti, prompt, entityHints);
+    const context = formatPromptContext(dedupeFacts(facts));
+    if (!context) {
+        process.exit(0);
+    }
     emitHookContext(event, context);
+    process.exit(0);
 }
 main().catch((error) => {
     console.error('[claude-code-memory-hook] fatal:', error instanceof Error ? error.message : String(error));

package/dist/scripts/codex-setup.js

@@ -11,6 +11,7 @@ function parseArgs(argv) {
         name: 'iranti',
         agent: 'codex_code',
         source: 'Codex',
+        useLocalScript: false,
     };
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
@@ -40,6 +41,15 @@ function parseArgs(argv) {
                 options.provider = next.trim();
                 index += 1;
                 break;
+            case '--project-env':
+                if (!next)
+                    throw new Error('--project-env requires a value.');
+                options.projectEnv = next.trim();
+                index += 1;
+                break;
+            case '--local-script':
+                options.useLocalScript = true;
+                break;
             case '--help':
             case '-h':
                 printHelp();
@@ -56,20 +66,40 @@ function printHelp() {
         'Configure Codex to use the local Iranti MCP server.',
         '',
         'Usage:',
-        '  ts-node scripts/codex-setup.ts [--name iranti] [--agent codex_code] [--source Codex] [--provider openai]',
+        '  ts-node scripts/codex-setup.ts [--name iranti] [--agent codex_code] [--source Codex] [--provider openai] [--project-env path] [--local-script]',
         '',
         'Notes:',
         '  - Registers a global Codex MCP entry using `codex mcp add`.',
-        '  - Does not store DATABASE_URL in Codex config; iranti-mcp loads .env from this repo at runtime.',
+        '  - Prefers the installed CLI path: `iranti mcp`.',
+        '  - Auto-detects .env.iranti from the current working directory and stores it as IRANTI_PROJECT_ENV.',
+        '  - Use --local-script only if you need to point Codex at this repo build directly.',
+        '  - Does not store DATABASE_URL in Codex config; iranti-mcp loads project/instance env at runtime.',
         '  - Replaces any existing MCP entry with the same name.',
     ].join('\n'));
 }
+function quoteForCmd(arg) {
+    if (arg.length === 0)
+        return '""';
+    if (!/[ \t"&()<>|^]/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '\\"')}"`;
+}
 function run(command, args, cwd) {
-    const result = (0, node_child_process_1.spawnSync)(command, args, {
-        cwd,
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    const result = process.platform === 'win32'
+        ? (0, node_child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', [
+            '/d',
+            '/c',
+            [command, ...args].map(quoteForCmd).join(' '),
+        ], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        })
+        : (0, node_child_process_1.spawnSync)(command, args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
     if (result.error) {
         throw result.error;
     }
@@ -88,14 +118,50 @@ function tryRun(command, args, cwd) {
         return null;
     }
 }
+function findPackageRoot(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 6; i += 1) {
+        const pkgPath = node_path_1.default.join(dir, 'package.json');
+        if (node_fs_1.default.existsSync(pkgPath)) {
+            return dir;
+        }
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return node_path_1.default.resolve(startDir, '..');
+}
+function resolveProjectEnv(options) {
+    const explicit = options.projectEnv?.trim();
+    if (explicit) {
+        const resolved = node_path_1.default.resolve(explicit);
+        if (!node_fs_1.default.existsSync(resolved)) {
+            throw new Error(`Project env file not found: ${resolved}`);
+        }
+        return resolved;
+    }
+    const candidate = node_path_1.default.resolve(process.cwd(), '.env.iranti');
+    return node_fs_1.default.existsSync(candidate) ? candidate : undefined;
+}
+function canUseInstalledIranti(repoRoot) {
+    try {
+        run('iranti', ['mcp', '--help'], repoRoot);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function main() {
     const options = parseArgs(process.argv.slice(2));
-    const repoRoot = node_path_1.default.resolve(__dirname, '..');
+    const repoRoot = findPackageRoot(__dirname);
     const mcpScript = node_path_1.default.join(repoRoot, 'dist', 'scripts', 'iranti-mcp.js');
-    if (!node_fs_1.default.existsSync(mcpScript)) {
-        throw new Error(`Missing build artifact: ${mcpScript}. Run "npm run build" first.`);
-    }
     run('codex', ['--version'], repoRoot);
+    const useInstalled = !options.useLocalScript && canUseInstalledIranti(repoRoot);
+    if (!useInstalled && !node_fs_1.default.existsSync(mcpScript)) {
+        throw new Error(`Missing build artifact: ${mcpScript}. Run "npm run build" first, or install iranti globally and rerun without --local-script.`);
+    }
     const existing = tryRun('codex', ['mcp', 'get', options.name, '--json'], repoRoot);
     if (existing !== null) {
         run('codex', ['mcp', 'remove', options.name], repoRoot);
@@ -109,16 +175,39 @@ function main() {
         '--env',
         `IRANTI_MCP_DEFAULT_SOURCE=${options.source}`,
     ];
+    const projectEnv = resolveProjectEnv(options);
+    if (projectEnv) {
+        addArgs.push('--env', `IRANTI_PROJECT_ENV=${projectEnv}`);
+    }
     if (options.provider) {
         addArgs.push('--env', `LLM_PROVIDER=${options.provider}`);
     }
-    addArgs.push('--', 'node', mcpScript);
+    if (useInstalled) {
+        addArgs.push('--', 'iranti', 'mcp');
+    }
+    else {
+        addArgs.push('--', 'node', mcpScript);
+    }
     run('codex', addArgs, repoRoot);
     const registered = run('codex', ['mcp', 'get', options.name], repoRoot);
     console.log(registered);
     console.log('');
     console.log('Codex is now configured to use Iranti through MCP.');
-    console.log(`Launch with: codex -C "${repoRoot}"`);
+    if (useInstalled) {
+        console.log('Registration target: installed CLI (`iranti mcp`)');
+        if (projectEnv) {
+            console.log(`Project binding: ${projectEnv}`);
+        }
+        console.log('Launch Codex in the project you want to bind to Iranti, for example:');
+        console.log('  codex -C C:\\path\\to\\your\\project');
+    }
+    else {
+        console.log(`Registration target: repo build (${mcpScript})`);
+        if (projectEnv) {
+            console.log(`Project binding: ${projectEnv}`);
+        }
+        console.log(`Launch with: codex -C "${repoRoot}"`);
+    }
 }
 main();
 //# sourceMappingURL=codex-setup.js.map

package/dist/scripts/iranti-cli.js

@@ -8,6 +8,7 @@ const fs_1 = __importDefault(require("fs"));
 const promises_1 = __importDefault(require("fs/promises"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
 const promises_2 = __importDefault(require("readline/promises"));
 const stream_1 = require("stream");
 const client_1 = require("../src/library/client");
@@ -118,6 +119,54 @@ function getPackageVersion() {
     }
     return '0.0.0';
 }
+function builtScriptPath(scriptName) {
+    return path_1.default.resolve(__dirname, `${scriptName}.js`);
+}
+async function handoffToScript(scriptName, rawArgs) {
+    const builtPath = builtScriptPath(scriptName);
+    if (fs_1.default.existsSync(builtPath)) {
+        await new Promise((resolve, reject) => {
+            const child = (0, child_process_1.spawn)(process.execPath, [builtPath, ...rawArgs], {
+                stdio: 'inherit',
+                env: process.env,
+            });
+            child.on('error', reject);
+            child.on('exit', (code, signal) => {
+                if (signal) {
+                    reject(new Error(`${scriptName} terminated with signal ${signal}`));
+                    return;
+                }
+                if ((code ?? 0) !== 0) {
+                    process.exit(code ?? 1);
+                }
+                resolve();
+            });
+        });
+        return;
+    }
+    const sourcePath = path_1.default.resolve(process.cwd(), 'scripts', `${scriptName}.ts`);
+    if (!fs_1.default.existsSync(sourcePath)) {
+        throw new Error(`Unable to locate ${scriptName} implementation.`);
+    }
+    await new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)('npx', ['ts-node', sourcePath, ...rawArgs], {
+            stdio: 'inherit',
+            env: process.env,
+            shell: process.platform === 'win32',
+        });
+        child.on('error', reject);
+        child.on('exit', (code, signal) => {
+            if (signal) {
+                reject(new Error(`${scriptName} terminated with signal ${signal}`));
+                return;
+            }
+            if ((code ?? 0) !== 0) {
+                process.exit(code ?? 1);
+            }
+            resolve();
+        });
+    });
+}
 async function ensureDir(dir) {
     await promises_1.default.mkdir(dir, { recursive: true });
 }
@@ -1077,7 +1126,12 @@ Diagnostics:
   iranti doctor [--instance <name>] [--scope user|system] [--env <file>] [--json]
   iranti status [--scope user|system] [--json]
   iranti upgrade [--json]
-`);
+
+Integrations:
+  iranti mcp [--help]
+  iranti claude-hook --event SessionStart|UserPromptSubmit [--project-env <path>] [--instance-env <path>] [--env-file <path>]
+  iranti codex-setup [--name iranti] [--agent codex_code] [--source Codex] [--provider openai] [--project-env <path>] [--local-script]
+  `);
 }
 async function main() {
     const args = parseArgs(process.argv.slice(2));
@@ -1150,6 +1204,18 @@ async function main() {
         await upgradeCommand(args);
         return;
     }
+    if (args.command === 'mcp') {
+        await handoffToScript('iranti-mcp', process.argv.slice(3));
+        return;
+    }
+    if (args.command === 'claude-hook') {
+        await handoffToScript('claude-code-memory-hook', process.argv.slice(3));
+        return;
+    }
+    if (args.command === 'codex-setup') {
+        await handoffToScript('codex-setup', process.argv.slice(3));
+        return;
+    }
     throw new Error(`Unknown command '${args.command}'. Run: iranti help`);
 }
 main().catch((err) => {

package/dist/scripts/iranti-mcp.js

@@ -32,35 +32,13 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-const dotenv_1 = __importDefault(require("dotenv"));
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const z = __importStar(require("zod/v4"));
 const sdk_1 = require("../src/sdk");
-function loadEnv() {
-    const explicitPath = process.env.IRANTI_ENV_FILE?.trim();
-    const candidates = explicitPath
-        ? [explicitPath]
-        : [
-            node_path_1.default.resolve(process.cwd(), '.env'),
-            node_path_1.default.resolve(__dirname, '..', '.env'),
-            node_path_1.default.resolve(__dirname, '..', '..', '.env'),
-        ];
-    for (const candidate of candidates) {
-        if (candidate && node_fs_1.default.existsSync(candidate)) {
-            dotenv_1.default.config({ path: candidate });
-            return;
-        }
-    }
-    dotenv_1.default.config();
-}
-loadEnv();
+const runtimeEnv_1 = require("../src/lib/runtimeEnv");
+(0, runtimeEnv_1.loadRuntimeEnv)();
 function printHelp() {
     console.log([
         'Iranti MCP Server',
@@ -72,6 +50,8 @@ function printHelp() {
         'Environment:',
         '  DATABASE_URL                  PostgreSQL connection string (required)',
         '  LLM_PROVIDER                  Optional Iranti provider override',
+        '  IRANTI_PROJECT_ENV            Optional project binding path (.env.iranti)',
+        '  IRANTI_INSTANCE_ENV           Optional instance env path',
         '  IRANTI_MCP_DEFAULT_AGENT      Default agent id (default: claude_code)',
         '  IRANTI_MCP_AGENT_NAME         Default agent display name',
         '  IRANTI_MCP_AGENT_DESCRIPTION  Default agent description',
@@ -89,7 +69,9 @@ function requireConnectionString() {
     return connectionString;
 }
 function defaultAgentId() {
-    return process.env.IRANTI_MCP_DEFAULT_AGENT?.trim() || 'claude_code';
+    return process.env.IRANTI_MCP_DEFAULT_AGENT?.trim()
+        || process.env.IRANTI_AGENT_ID?.trim()
+        || 'claude_code';
 }
 function defaultWriteSource() {
     return process.env.IRANTI_MCP_DEFAULT_SOURCE?.trim() || 'ClaudeCode';
@@ -162,7 +144,7 @@ async function main() {
     await ensureDefaultAgent(iranti);
     const server = new mcp_js_1.McpServer({
         name: 'iranti-mcp',
-        version: '0.1.1',
+        version: '0.1.3',
     });
     server.registerTool('iranti_handshake', {
         description: 'Initialize or refresh Claude working memory for the current task.',

package/dist/scripts/seed.js

@@ -15,7 +15,7 @@ const STAFF_ENTRIES = [
         entityId: 'librarian',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.1.1',
+            version: '0.1.3',
             rules: [
                 'All writes from external agents go through the Librarian — never directly to the database',
                 'Check for existing entries before every write',
@@ -39,7 +39,7 @@ const STAFF_ENTRIES = [
         entityId: 'attendant',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.1.1',
+            version: '0.1.3',
             rules: [
                 'Assigned one-per-external-agent — serve the agent, not the user',
                 'On handshake: read AGENTS.md and MCP config, query Librarian for relevant rules and task context',
@@ -61,7 +61,7 @@ const STAFF_ENTRIES = [
         entityId: 'archivist',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.1.1',
+            version: '0.1.3',
             rules: [
                 'Run on schedule or when conflict flags exceed threshold — not on every write',
                 'Scan for expired, low-confidence, flagged, and duplicate entries',
@@ -82,7 +82,7 @@ const STAFF_ENTRIES = [
         entityType: 'system',
         entityId: 'library',
         key: 'schema_version',
-        valueRaw: { version: '0.1.1' },
+        valueRaw: { version: '0.1.3' },
         valueSummary: 'Current Library schema version.',
         confidence: 100,
         source: 'seed',
@@ -95,7 +95,7 @@ const STAFF_ENTRIES = [
         key: 'initialization_log',
         valueRaw: {
             initializedAt: new Date().toISOString(),
-            seedVersion: '0.1.1',
+            seedVersion: '0.1.3',
         },
         valueSummary: 'Record of when and how this Library was initialized.',
         confidence: 100,
@@ -108,7 +108,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'core_schema',
         valueRaw: {
-            version: '0.1.1',
+            version: '0.1.3',
             states: ['candidate', 'provisional', 'canonical'],
             coreEntityTypes: [
                 'person',
@@ -156,7 +156,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'extension_registry',
         valueRaw: {
-            version: '0.1.1',
+            version: '0.1.3',
             namespaces: {
                 education: {
                     status: 'provisional',
@@ -187,7 +187,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'candidate_terms',
         valueRaw: {
-            version: '0.1.1',
+            version: '0.1.3',
             terms: [],
         },
         valueSummary: 'Staging area for ontology terms detected repeatedly but not yet promoted.',
@@ -201,7 +201,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'promotion_policy',
         valueRaw: {
-            version: '0.1.1',
+            version: '0.1.3',
             candidateToProvisional: {
                 minSeenCount: 3,
                 minDistinctAgents: 2,
@@ -237,7 +237,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'change_log',
         valueRaw: {
-            version: '0.1.1',
+            version: '0.1.3',
             events: [
                 {
                     at: new Date().toISOString(),

package/dist/src/api/server.js

@@ -69,7 +69,7 @@ app.use(express_1.default.json({ limit: process.env.IRANTI_MAX_BODY_BYTES ?? '25
 app.get(ROUTES.health, (_req, res) => {
     res.json({
         status: 'ok',
-        version: '0.1.1',
+        version: '0.1.3',
         provider: process.env.LLM_PROVIDER ?? 'mock',
     });
 });

package/dist/src/lib/runtimeEnv.d.ts

@@ -0,0 +1,15 @@
+type RuntimeEnvOptions = {
+    cwd?: string;
+    payloadCwd?: string;
+    projectEnvFile?: string;
+    instanceEnvFile?: string;
+    explicitEnvFile?: string;
+};
+type RuntimeEnvLoadResult = {
+    loadedFiles: string[];
+    projectEnvFile?: string;
+    instanceEnvFile?: string;
+};
+export declare function loadRuntimeEnv(options?: RuntimeEnvOptions): RuntimeEnvLoadResult;
+export {};
+//# sourceMappingURL=runtimeEnv.d.ts.map

package/dist/src/lib/runtimeEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeEnv.d.ts","sourceRoot":"","sources":["../../../src/lib/runtimeEnv.ts"],"names":[],"mappings":"AAIA,KAAK,iBAAiB,GAAG;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG;IACxB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAuDF,wBAAgB,cAAc,CAAC,OAAO,GAAE,iBAAsB,GAAG,oBAAoB,CAsCpF"}

package/dist/src/lib/runtimeEnv.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRuntimeEnv = loadRuntimeEnv;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const dotenv_1 = __importDefault(require("dotenv"));
+function parseEnvFile(filePath) {
+    const raw = fs_1.default.readFileSync(filePath, 'utf-8');
+    return dotenv_1.default.parse(raw);
+}
+function applyEnvVars(vars, initialEnvKeys) {
+    for (const [key, value] of Object.entries(vars)) {
+        if (initialEnvKeys.has(key))
+            continue;
+        process.env[key] = value;
+    }
+}
+function dedupePaths(paths) {
+    const seen = new Set();
+    const out = [];
+    for (const candidate of paths) {
+        if (!candidate)
+            continue;
+        const resolved = path_1.default.resolve(candidate);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        out.push(resolved);
+    }
+    return out;
+}
+function findProjectEnvFile(options) {
+    const explicit = options.projectEnvFile?.trim() || process.env.IRANTI_PROJECT_ENV?.trim();
+    if (explicit && fs_1.default.existsSync(explicit))
+        return path_1.default.resolve(explicit);
+    const candidates = dedupePaths([
+        options.payloadCwd ? path_1.default.join(options.payloadCwd, '.env.iranti') : null,
+        options.cwd ? path_1.default.join(options.cwd, '.env.iranti') : null,
+        path_1.default.join(process.cwd(), '.env.iranti'),
+    ]);
+    return candidates.find((candidate) => fs_1.default.existsSync(candidate));
+}
+function findFallbackEnvFile(options) {
+    const explicit = options.explicitEnvFile?.trim() || process.env.IRANTI_ENV_FILE?.trim();
+    if (explicit && fs_1.default.existsSync(explicit))
+        return path_1.default.resolve(explicit);
+    const candidates = dedupePaths([
+        options.payloadCwd ? path_1.default.join(options.payloadCwd, '.env') : null,
+        options.cwd ? path_1.default.join(options.cwd, '.env') : null,
+        path_1.default.join(process.cwd(), '.env'),
+        path_1.default.resolve(__dirname, '..', '..', '.env'),
+        path_1.default.resolve(__dirname, '..', '..', '..', '.env'),
+    ]);
+    return candidates.find((candidate) => fs_1.default.existsSync(candidate));
+}
+function loadRuntimeEnv(options = {}) {
+    const loadedFiles = [];
+    const initialEnvKeys = new Set(Object.keys(process.env));
+    const fallbackEnvFile = findFallbackEnvFile(options);
+    if (fallbackEnvFile) {
+        applyEnvVars(parseEnvFile(fallbackEnvFile), initialEnvKeys);
+        loadedFiles.push(fallbackEnvFile);
+    }
+    const projectEnvFile = findProjectEnvFile(options);
+    const projectEnv = projectEnvFile && fs_1.default.existsSync(projectEnvFile)
+        ? parseEnvFile(projectEnvFile)
+        : null;
+    const instanceEnvFile = options.instanceEnvFile?.trim()
+        || process.env.IRANTI_INSTANCE_ENV?.trim()
+        || projectEnv?.IRANTI_INSTANCE_ENV;
+    const resolvedInstanceEnvFile = instanceEnvFile && fs_1.default.existsSync(instanceEnvFile)
+        ? path_1.default.resolve(instanceEnvFile)
+        : undefined;
+    if (resolvedInstanceEnvFile) {
+        applyEnvVars(parseEnvFile(resolvedInstanceEnvFile), initialEnvKeys);
+        loadedFiles.push(resolvedInstanceEnvFile);
+    }
+    if (projectEnvFile && projectEnv) {
+        applyEnvVars(projectEnv, initialEnvKeys);
+        loadedFiles.push(projectEnvFile);
+    }
+    return {
+        loadedFiles,
+        projectEnvFile,
+        instanceEnvFile: resolvedInstanceEnvFile,
+    };
+}
+//# sourceMappingURL=runtimeEnv.js.map

package/dist/src/lib/runtimeEnv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeEnv.js","sourceRoot":"","sources":["../../../src/lib/runtimeEnv.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iranti",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Memory infrastructure for multi-agent AI systems",
   "main": "dist/src/sdk/index.js",
   "files": [