engram-sdk 0.5.7 → 0.6.1

package/dist/cli.js

@@ -4,13 +4,67 @@ import { runEval } from './eval.js';
 import { checkForUpdates, getVersion } from './update-check.js';
 import * as telemetry from './telemetry.js';
 import { renderTree as renderMemoryTree, animateGrowth } from './memory-tree.js';
-import { HostedClient, getHostedConfig, setHostedConfig, clearHostedConfig, federatedRecall } from './hosted-client.js';
+import { HostedClient, getHostedConfig, setHostedConfig, clearHostedConfig, federatedRecall, getWriteQueue } from './hosted-client.js';
+import { classifySensitive } from './content-filter.js';
 import path from 'path';
 import { homedir } from 'os';
 import { parseArgs } from 'util';
 // ============================================================
 // Engram CLI — Quick interface for testing & exploration
 // ============================================================
+function getEngramInstructions() {
+    return `
+## Engram — Persistent Memory
+
+You have Engram memory tools via MCP. **Use them proactively** — do not wait to be asked.
+
+### Session Start
+- ALWAYS call \`engram_briefing\` at the start of every session to load context from past sessions.
+
+### What to Remember (call \`engram_remember\` immediately)
+Store ANY of these the moment you encounter them — do not batch, do not wait:
+
+**From the user:**
+- Preferences, opinions, personal facts, decisions, corrections
+- "I prefer X", "we decided Y", "actually it's Z"
+
+**From your own work:**
+- When you read a file and synthesize useful knowledge (style guides, architecture patterns, workflow rules) — store the synthesis
+- When you figure out HOW the user works (communication style, review habits, tool preferences) — store the observation
+- When you discover project conventions, naming patterns, or implicit rules — store them
+- When you build something and learn what works vs what doesn't — store the lesson
+
+**The rule:** If this knowledge would be useful in a future session, store it NOW. Don't assume you'll remember — you won't.
+
+### Team Vault
+- When connected to a hosted vault, memories are shared with your team by default
+- Use \`engram_private_session\` if the user wants a confidential session (nothing leaves the local machine)
+- Use \`engram_invite\` to add a teammate when asked ("add Brian to engram", "invite tyler@company.com")
+- Recall always searches both local + shared vaults, so you see everything
+
+### Asking Questions
+- When you need to ANSWER a question from memory: call \`engram_ask\` — it returns a synthesized answer with confidence, not raw memories
+- When you need raw memory objects for processing: call \`engram_recall\`
+- Prefer \`engram_ask\` for user-facing answers, \`engram_recall\` for your own analysis
+
+### Alerts
+- Periodically call \`engram_alerts\` to check for pending commitments, stale follow-ups, and contradictions
+- Alerts are included in \`engram_briefing\` automatically, but call separately if you need a quick check
+
+### Auditing External Memory
+- If you maintain a CLAUDE.md, MEMORY.md, or similar file: periodically call \`engram_audit\` with its contents
+- It will flag any claims that are outdated or contradicted by newer vault data
+
+### Before Compacting / Session End
+- Before context compaction or ending a session, call \`engram_checkpoint\` with a summary of:
+  - Decisions made and their reasoning
+  - Facts learned or corrected (especially things that changed from what you previously knew)
+  - Commitments and next steps
+  - Current project state
+- This extracts durable memories from your context window before it is lost
+- Your context window is the most accurate source of truth you have — and the most volatile. Save it.
+`;
+}
 const HELP = `
 engram — Universal memory layer for AI agents
 
@@ -18,6 +72,7 @@ Usage:
   engram init                        Set up Engram for Claude Code / Cursor / VS Code / Gemini CLI / Codex
   engram setup                       Alias for init
   engram import --claude-code        Import memory from Claude Code (no 200-line limit)
+  engram import --obsidian <path>    Import an Obsidian vault (wikilinks, tags, frontmatter)
   engram mcp                         Start the MCP server (stdio transport)
   engram mcp --http                  Start the MCP server (HTTP transport, port 3801)
   engram shadow start                Start shadow mode (server + watcher, background)
@@ -37,6 +92,7 @@ Usage:
   engram telemetry show              View telemetry status and pending events
   engram connect <url> --api-key <k>  Connect to a hosted vault
   engram disconnect                  Disconnect from hosted vault
+  engram invite <email>              Invite a teammate to your shared vault
   engram config set telemetry false  Opt out of anonymous usage data
   engram config get telemetry        Check telemetry status
 
@@ -70,6 +126,7 @@ function parseCliArgs() {
             salience: { type: 'string', default: '' },
             confidence: { type: 'string', default: '' },
             'claude-code': { type: 'boolean', default: false },
+            obsidian: { type: 'string', default: '' },
             'include-sessions': { type: 'boolean', default: false },
             'dry-run': { type: 'boolean', default: false },
             'max-sessions': { type: 'string', default: '10' },
@@ -78,7 +135,10 @@ function parseCliArgs() {
             private: { type: 'boolean', default: false },
             local: { type: 'boolean', default: false },
             'api-key': { type: 'string', default: '' },
+            role: { type: 'string', default: 'member' },
             verbose: { type: 'boolean', default: false },
+            all: { type: 'boolean', default: false },
+            since: { type: 'string', default: '' },
         },
     });
     return { values, positionals };
@@ -403,51 +463,7 @@ async function runInit(values) {
     // 5. Add Engram instructions to CLAUDE.md (if Claude dir exists)
     if (hasClaudeDir) {
         const claudeMdPath = join(home, '.claude', 'CLAUDE.md');
-        const engramBlock = `
-## Engram — Persistent Memory
-
-You have Engram memory tools via MCP. **Use them proactively** — do not wait to be asked.
-
-### Session Start
-- ALWAYS call \`engram_briefing\` at the start of every session to load context from past sessions.
-
-### What to Remember (call \`engram_remember\` immediately)
-Store ANY of these the moment you encounter them — do not batch, do not wait:
-
-**From the user:**
-- Preferences, opinions, personal facts, decisions, corrections
-- "I prefer X", "we decided Y", "actually it's Z"
-
-**From your own work:**
-- When you read a file and synthesize useful knowledge (style guides, architecture patterns, workflow rules) — store the synthesis
-- When you figure out HOW the user works (communication style, review habits, tool preferences) — store the observation
-- When you discover project conventions, naming patterns, or implicit rules — store them
-- When you build something and learn what works vs what doesn't — store the lesson
-
-**The rule:** If this knowledge would be useful in a future session, store it NOW. Don't assume you'll remember — you won't.
-
-### Asking Questions
-- When you need to ANSWER a question from memory: call \`engram_ask\` — it returns a synthesized answer with confidence, not raw memories
-- When you need raw memory objects for processing: call \`engram_recall\`
-- Prefer \`engram_ask\` for user-facing answers, \`engram_recall\` for your own analysis
-
-### Alerts
-- Periodically call \`engram_alerts\` to check for pending commitments, stale follow-ups, and contradictions
-- Alerts are included in \`engram_briefing\` automatically, but call separately if you need a quick check
-
-### Auditing External Memory
-- If you maintain a CLAUDE.md, MEMORY.md, or similar file: periodically call \`engram_audit\` with its contents
-- It will flag any claims that are outdated or contradicted by newer vault data
-
-### Before Compacting / Session End
-- Before context compaction or ending a session, call \`engram_checkpoint\` with a summary of:
-  - Decisions made and their reasoning
-  - Facts learned or corrected (especially things that changed from what you previously knew)
-  - Commitments and next steps
-  - Current project state
-- This extracts durable memories from your context window before it is lost
-- Your context window is the most accurate source of truth you have — and the most volatile. Save it.
-`;
+        const engramBlock = getEngramInstructions();
         let claudeMd = '';
         if (existsSync(claudeMdPath)) {
             claudeMd = readFileSync(claudeMdPath, 'utf-8');
@@ -497,6 +513,9 @@ Store ANY of these the moment you encounter them — do not batch, do not wait:
                 'mcp__engram__engram_entities',
                 'mcp__engram__engram_stats',
                 'mcp__engram__engram_ingest',
+                'mcp__engram__engram_private_session',
+                'mcp__engram__engram_shared_session',
+                'mcp__engram__engram_invite',
             ];
             let added = 0;
             for (const tool of engramTools) {
@@ -913,6 +932,24 @@ async function main() {
                 await vault.close();
             }
         }
+        else if (values.obsidian) {
+            const { importObsidian } = await import('./import.js');
+            const vault = createVault(values);
+            try {
+                const result = await importObsidian({
+                    vault,
+                    vaultPath: values.obsidian,
+                    dryRun: values['dry-run'],
+                    verbose: values.verbose,
+                });
+                if (values.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+            }
+            finally {
+                await vault.close();
+            }
+        }
         else {
             console.log(`
 engram import — Migrate memory from other AI tools
@@ -922,6 +959,8 @@ Usage:
   engram import --claude-code --dry-run      Preview what would be imported
   engram import --claude-code --include-sessions  Also parse session transcripts
   engram import --claude-code --verbose      Show detailed progress
+  engram import --obsidian /path/to/vault    Import from an Obsidian vault
+  engram import --obsidian ~/vault --dry-run Preview what would be imported
 
 Options:
   --include-sessions     Parse JSONL session transcripts for high-signal messages
@@ -1046,12 +1085,62 @@ Engram has no limit, semantic search, and cross-project intelligence.
                 console.log(green('✓ API key verified'));
             setHostedConfig(url, apiKey);
             console.log(green('\n✓ Saved to ~/.config/engram/config.json'));
-            console.log('\nYou can now use:');
-            console.log('  engram remember "..."             Stores to shared vault (default when connected)');
-            console.log('  engram remember "..." --private   Keeps memory local-only');
-            console.log('  engram recall "..."               Searches both local + shared');
-            console.log('  engram recall "..." --local       Search only local vault');
-            console.log('  engram stats --shared             Shared vault stats\n');
+            // Auto-setup agent instructions if not already done
+            const { existsSync, readFileSync, writeFileSync } = await import('fs');
+            const { join } = await import('path');
+            const home = homedir();
+            const claudeDir = join(home, '.claude');
+            const claudeMdPath = join(claudeDir, 'CLAUDE.md');
+            if (existsSync(claudeDir)) {
+                let claudeMd = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, 'utf-8') : '';
+                if (!claudeMd.includes('## Engram')) {
+                    console.log('\n📋 Setting up agent instructions...');
+                    // Run init-style CLAUDE.md setup
+                    const engramBlock = getEngramInstructions();
+                    writeFileSync(claudeMdPath, claudeMd + '\n' + engramBlock.trim() + '\n');
+                    console.log(green('  ✓ Added Engram instructions to ~/.claude/CLAUDE.md'));
+                    console.log('  Your agent will now use Engram proactively in every session.');
+                }
+                // Auto-approve MCP tools in Claude Code settings
+                const settingsPath = join(claudeDir, 'settings.json');
+                if (existsSync(settingsPath)) {
+                    try {
+                        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+                        const allow = settings.permissions?.allow ?? [];
+                        const engramTools = [
+                            'mcp__engram__engram_remember', 'mcp__engram__engram_recall',
+                            'mcp__engram__engram_surface', 'mcp__engram__engram_briefing',
+                            'mcp__engram__engram_consolidate', 'mcp__engram__engram_connect',
+                            'mcp__engram__engram_forget', 'mcp__engram__engram_entities',
+                            'mcp__engram__engram_stats', 'mcp__engram__engram_ingest',
+                            'mcp__engram__engram_private_session', 'mcp__engram__engram_shared_session',
+                            'mcp__engram__engram_invite',
+                        ];
+                        let added = 0;
+                        for (const tool of engramTools) {
+                            if (!allow.includes(tool)) {
+                                allow.push(tool);
+                                added++;
+                            }
+                        }
+                        if (added > 0) {
+                            if (!settings.permissions)
+                                settings.permissions = {};
+                            settings.permissions.allow = allow;
+                            writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+                            console.log(green(`  ✓ Auto-approved ${added} Engram tools in Claude Code`));
+                        }
+                    }
+                    catch { /* settings parse error, skip */ }
+                }
+            }
+            console.log('\n✅ You\'re all set! Your agent will now:');
+            console.log('  • Store memories to the shared team vault automatically');
+            console.log('  • Recall context from both local + shared vaults');
+            console.log('  • Use /engram-private to switch a session to local-only mode');
+            console.log('');
+            console.log(`  📊 View your team dashboard at ${green('https://app.engram.fyi')}`);
+            console.log('');
         }
         catch (err) {
             console.error(`\n✗ Connection failed: ${err.message}`);
@@ -1059,6 +1148,34 @@ Engram has no limit, semantic search, and cross-project intelligence.
         }
         return;
     }
+    if (command === 'invite') {
+        const email = positionals[1];
+        if (!email) {
+            console.error('Usage: engram invite <email> [--role member|readonly]');
+            process.exit(1);
+        }
+        const hostedConfig = getHostedConfig();
+        if (!hostedConfig) {
+            console.error('Error: not connected to a hosted vault. Run: engram connect <url> --api-key <key>');
+            process.exit(1);
+        }
+        try {
+            const client = new HostedClient(hostedConfig);
+            const role = values.role ?? 'member';
+            const result = await client.invite(email, role);
+            console.log(green(`✓ ${result.message}`));
+            console.log(`\nSend them this:\n`);
+            console.log(`  npm install -g engram-sdk@latest`);
+            console.log(`  engram connect https://api.engram.fyi --api-key ${result.account.apiKey}`);
+            console.log(`\nThat's it — their agent will automatically share memories with the team.`);
+            console.log(`Team dashboard: ${green('https://app.engram.fyi')}`);
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        return;
+    }
     if (command === 'disconnect') {
         const existing = getHostedConfig();
         if (!existing) {
@@ -1108,14 +1225,50 @@ Engram has no limit, semantic search, and cross-project intelligence.
                     input.salience = parseFloat(values.salience);
                 if (values.confidence)
                     input.confidence = parseFloat(values.confidence);
-                const mem = await client.remember(input);
-                if (values.json) {
-                    console.log(JSON.stringify(mem, null, 2));
+                // Always write locally first (write-through)
+                const localVault = createVault(values);
+                const localMem = localVault.remember(input);
+                // Check for sensitive content before hosted write
+                const sensitivity = classifySensitive(text);
+                if (sensitivity.sensitive) {
+                    if (values.json) {
+                        console.log(JSON.stringify({ ...localMem, warning: `Stored locally only — sensitive content detected (${sensitivity.reason})` }, null, 2));
+                    }
+                    else {
+                        console.log(yellow(`⚠️ Stored locally only — sensitive content detected (${sensitivity.reason})`));
+                        printMemory(localMem, false);
+                    }
+                    await localVault.close();
+                    return;
                 }
-                else {
-                    console.log(green('✓ Remembered (hosted):'));
-                    printMemory(mem, false);
+                // Write-through to hosted (async with retry queue)
+                try {
+                    const mem = await client.remember(input);
+                    if (values.json) {
+                        console.log(JSON.stringify(mem, null, 2));
+                    }
+                    else {
+                        console.log(green('✓ Remembered (local + shared):'));
+                        printMemory(mem, false);
+                    }
+                }
+                catch (err) {
+                    getWriteQueue().enqueue(input);
+                    if (values.json) {
+                        console.log(JSON.stringify(localMem, null, 2));
+                    }
+                    else {
+                        console.log(yellow(`⚠️ Hosted write failed (queued for retry): ${err.message}`));
+                        console.log(green('✓ Remembered locally:'));
+                        printMemory(localMem, false);
+                    }
+                }
+                // Flush any queued writes
+                const wq = getWriteQueue();
+                if (wq.length > 0) {
+                    wq.flush(client).catch(() => { });
                 }
+                await localVault.close();
                 return;
             }
             case 'stats': {
@@ -1365,8 +1518,10 @@ Engram has no limit, semantic search, and cross-project intelligence.
             }
             case 'sleep':
             case 'consolidate': {
-                console.log(yellow('⏳ Running consolidation...'));
-                const report = await vault.consolidate();
+                const allFlag = values.all ?? process.argv.includes('--all');
+                const sinceFlag = (values.since || undefined);
+                console.log(yellow(`⏳ Running consolidation${allFlag ? ' (all episodes)' : sinceFlag ? ` (since ${sinceFlag})` : ''}...`));
+                const report = await vault.consolidate({ all: !!allFlag, since: sinceFlag });
                 if (values.json) {
                     console.log(JSON.stringify(report, null, 2));
                 }