@pella-labs/pinakes 0.1.0

package/README.md

@@ -0,0 +1,208 @@
+# kg-mcp
+
+Local stdio MCP server that indexes a [Karpathy-style](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) two-level knowledge wiki (project + personal) into SQLite and exposes it to any coding LLM via [Cloudflare-style code-mode](https://blog.cloudflare.com/code-mode-mcp/).
+
+**Two tools. One process. Works with any MCP client.**
+
+- `kg_search` — hybrid FTS5 + vector search ranked by Reciprocal Rank Fusion
+- `kg_execute` — run JS in a QuickJS sandbox with `kg.project.*` bindings for search, graph traversal, wiki writes, and more
+
+Markdown is canonical. SQLite is the index. If the index is corrupted or lost, rebuild it from markdown.
+
+## Install
+
+```bash
+# Clone and build
+git clone <repo-url> && cd knowledge-graph
+pnpm install
+pnpm run build
+```
+
+Requires **Node.js 24 LTS** (`^24.10.0`) and **pnpm** (`>=10.30.0`).
+
+## Quick start
+
+```bash
+# Initialize a wiki directory
+mkdir -p .kg/wiki
+echo "# My Project\nSome knowledge about the project." > .kg/wiki/overview.md
+
+# Start the stdio server
+pnpm run kg -- serve --wiki-path .kg/wiki
+
+# Or rebuild the index from existing markdown
+pnpm run kg -- rebuild --wiki-path .kg/wiki
+```
+
+## MCP client configuration
+
+### Claude Code
+
+```bash
+claude mcp add kg-mcp -- npx tsx /path/to/knowledge-graph/src/cli/index.ts serve --wiki-path /path/to/project/.kg/wiki
+```
+
+Or add to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "kg-mcp": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/knowledge-graph/src/cli/index.ts", "serve", "--wiki-path", "/path/to/project/.kg/wiki"]
+    }
+  }
+}
+```
+
+### Goose
+
+Add to `~/.config/goose/profiles.yaml`:
+
+```yaml
+extensions:
+  kg-mcp:
+    name: kg-mcp
+    type: stdio
+    cmd: npx
+    args:
+      - tsx
+      - /path/to/knowledge-graph/src/cli/index.ts
+      - serve
+      - --wiki-path
+      - /path/to/project/.kg/wiki
+```
+
+### Codex
+
+```bash
+export CODEX_MCP_SERVERS='{"kg-mcp":{"command":"npx","args":["tsx","/path/to/knowledge-graph/src/cli/index.ts","serve","--wiki-path","/path/to/project/.kg/wiki"]}}'
+```
+
+### OpenCode
+
+Add to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "kg-mcp": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/knowledge-graph/src/cli/index.ts", "serve", "--wiki-path", "/path/to/project/.kg/wiki"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to Cursor settings (Settings > MCP Servers):
+
+```json
+{
+  "mcpServers": {
+    "kg-mcp": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/knowledge-graph/src/cli/index.ts", "serve", "--wiki-path", "/path/to/project/.kg/wiki"]
+    }
+  }
+}
+```
+
+## Example queries
+
+### Search
+
+```
+kg_search({ query: "authentication flow", scope: "project" })
+```
+
+### Execute (code-mode)
+
+```javascript
+// Full-text search
+kg_execute({ code: `return kg.project.fts("bcrypt")` })
+
+// Node lookup + neighbors
+kg_execute({ code: `
+  const node = kg.project.get("sha1-id-here");
+  const neighbors = kg.project.neighbors(node.id, { depth: 2 });
+  return { node, neighbors };
+` })
+
+// Write a wiki page
+kg_execute({ code: `
+  return kg.project.write("decisions/use-postgres.md", "# Use PostgreSQL\\nWe chose Postgres because...");
+` })
+
+// Query across both scopes
+kg_execute({
+  code: `return kg.project.hybrid("deploy process")`,
+  scope: "both"
+})
+```
+
+## CLI commands
+
+```bash
+kg serve   --wiki-path <dir>     # Start the stdio MCP server
+kg rebuild --wiki-path <dir>     # Full rebuild from markdown
+kg status                        # Health check + row counts
+kg audit   [--tail] [--n 20]     # Tail the audit log
+kg purge   --scope <s> --confirm # Delete a scope's DB
+kg export  --scope <s> [--out f] # Dump nodes + edges as JSON
+kg import  --scope <s> --in f    # Restore from dump
+```
+
+## Embedder configuration
+
+The default embedder is bundled (`Xenova/all-MiniLM-L6-v2`, 384 dimensions, runs locally). You can upgrade to a more capable embedder via environment variables:
+
+### Ollama (local, free)
+
+```bash
+export KG_EMBED_PROVIDER=ollama
+export KG_OLLAMA_URL=http://localhost:11434
+export KG_OLLAMA_MODEL=nomic-embed-text
+```
+
+### Voyage AI (cloud, paid)
+
+```bash
+export KG_EMBED_PROVIDER=voyage
+export KG_VOYAGE_API_KEY=your-key-here
+```
+
+### OpenAI (cloud, paid)
+
+```bash
+export KG_EMBED_PROVIDER=openai
+export KG_OPENAI_API_KEY=your-key-here
+```
+
+Changing the embedder requires a full rebuild (`kg rebuild`) since the vector dimensions change.
+
+## Architecture
+
+- **Single process**: MCP server, file watcher, SQLite writer, read pool, embedder, and QuickJS sandbox all in one Node process
+- **Single writer, multi reader**: one writer connection + 2 reader connections per DB, WAL mode
+- **Two-level KG**: project wiki (`.kg/wiki/`) + personal wiki (`~/.kg/wiki/`), fully isolated by default
+- **Privacy invariant**: personal KG bindings are only injected when `scope` includes `'personal'`
+- **Budget gate**: every response stays under `max_tokens` (default 5000, hard cap 25000)
+- **Deterministic IDs**: `sha1(scope + ':' + source_uri + ':' + section_path)` means re-indexing is idempotent
+
+## Development
+
+```bash
+pnpm install
+pnpm run dev              # Watch mode
+pnpm run test             # Run tests (vitest)
+pnpm run test:privacy     # Privacy adversarial suite (merge blocker)
+pnpm run test:budget      # Budget gate adversarial suite
+pnpm run typecheck        # tsc --noEmit
+pnpm run lint             # eslint
+```
+
+## License
+
+See LICENSE file.

package/dist/cli/audit.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `kg audit --tail` — tail the kg_audit table for a scope's DB.
+ *
+ * Reads the most recent N audit rows (default 20) and prints them as
+ * newline-delimited JSON. Strictly read-only.
+ */
+export interface AuditOptions {
+    /** Number of rows to show (default 20) */
+    n?: number;
+    /** Project DB path */
+    dbPath?: string;
+    /** Wiki path (used to derive default dbPath) */
+    wikiPath?: string;
+    /** Personal DB path */
+    profileDbPath?: string;
+    /** Which scope to tail: 'project' | 'personal' (default 'project') */
+    scope?: 'project' | 'personal';
+}
+export interface AuditRow {
+    id: number;
+    ts: number;
+    tool_name: string;
+    scope_requested: string;
+    caller_ctx: string | null;
+    response_tokens: number | null;
+    error: string | null;
+}
+export declare function auditCommand(options: AuditOptions): AuditRow[];
+export declare function renderAudit(rows: AuditRow[]): string;
+//# sourceMappingURL=audit.d.ts.map

package/dist/cli/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/cli/audit.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,QAAQ,EAAE,CAqB9D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,CAGpD"}

package/dist/cli/audit.js

@@ -0,0 +1,49 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { closeDb, openDb } from '../db/client.js';
+export function auditCommand(options) {
+    const scope = options.scope ?? 'project';
+    const n = options.n ?? 20;
+    const dbPath = resolveDbPath(options, scope);
+    if (!existsSync(dbPath)) {
+        return [];
+    }
+    const bundle = openDb(dbPath, { runMigrations: false });
+    try {
+        const rows = bundle.writer
+            .prepare(`SELECT id, ts, tool_name, scope_requested, caller_ctx, response_tokens, error
+         FROM kg_audit ORDER BY id DESC LIMIT ?`)
+            .all(n);
+        return rows.reverse(); // chronological order
+    }
+    finally {
+        closeDb(bundle);
+    }
+}
+export function renderAudit(rows) {
+    if (rows.length === 0)
+        return '(no audit rows)';
+    return rows.map((r) => JSON.stringify(r)).join('\n');
+}
+// ----------------------------------------------------------------------------
+// Path helpers (shared pattern with status.ts)
+// ----------------------------------------------------------------------------
+function resolveDbPath(options, scope) {
+    if (scope === 'personal') {
+        if (options.profileDbPath)
+            return resolveAbs(options.profileDbPath);
+        const env = process.env.KG_PROFILE_PATH;
+        const profileDir = env ? resolveAbs(env) : resolve(homedir(), '.pharos/profile');
+        return resolve(profileDir, 'kg.db');
+    }
+    if (options.dbPath)
+        return resolveAbs(options.dbPath);
+    if (options.wikiPath)
+        return resolve(dirname(resolveAbs(options.wikiPath)), 'kg.db');
+    return resolve(process.cwd(), '.pharos/kg.db');
+}
+function resolveAbs(p) {
+    return isAbsolute(p) ? p : resolve(process.cwd(), p);
+}
+//# sourceMappingURL=audit.js.map

package/dist/cli/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/cli/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAgClD,MAAM,UAAU,YAAY,CAAC,OAAqB;IAChD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC;IACzC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAE7C,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM;aACvB,OAAO,CACN;gDACwC,CACzC;aACA,GAAG,CAAC,CAAC,CAAe,CAAC;QACxB,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,sBAAsB;IAC/C,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,iBAAiB,CAAC;IAChD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvD,CAAC;AAED,+EAA+E;AAC/E,+CAA+C;AAC/C,+EAA+E;AAE/E,SAAS,aAAa,CAAC,OAAqB,EAAE,KAA6B;IACzE,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,aAAa;YAAE,OAAO,UAAU,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACpE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;QACxC,MAAM,UAAU,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,iBAAiB,CAAC,CAAC;QACjF,OAAO,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,OAAO,CAAC,MAAM;QAAE,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,OAAO,CAAC,QAAQ;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACrF,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,eAAe,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/cli/export.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `kg export --scope <s> [--out file.json]` — dump a scope's nodes + edges
+ * as JSON for backup / migration / debugging.
+ *
+ * Output format:
+ * ```json
+ * {
+ *   "scope": "project",
+ *   "exported_at": "2026-04-09T...",
+ *   "nodes": [ ... ],
+ *   "edges": [ ... ],
+ *   "chunks": [ ... ]
+ * }
+ * ```
+ */
+export interface ExportOptions {
+    scope: 'project' | 'personal';
+    out?: string;
+    dbPath?: string;
+    wikiPath?: string;
+    profileDbPath?: string;
+}
+export interface ExportData {
+    scope: string;
+    exported_at: string;
+    nodes: unknown[];
+    edges: unknown[];
+    chunks: unknown[];
+}
+export declare function exportCommand(options: ExportOptions): ExportData;
+export declare function renderExport(data: ExportData, outPath?: string): string;
+//# sourceMappingURL=export.d.ts.map

package/dist/cli/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/cli/export.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,UAAU,CAiDhE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAIvE"}

package/dist/cli/export.js

@@ -0,0 +1,73 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { closeDb, openDb } from '../db/client.js';
+export function exportCommand(options) {
+    const dbPath = resolveDbPath(options, options.scope);
+    if (!existsSync(dbPath)) {
+        return {
+            scope: options.scope,
+            exported_at: new Date().toISOString(),
+            nodes: [],
+            edges: [],
+            chunks: [],
+        };
+    }
+    const bundle = openDb(dbPath, { runMigrations: false });
+    try {
+        const nodes = bundle.writer
+            .prepare(`SELECT * FROM kg_nodes WHERE scope = ?`)
+            .all(options.scope);
+        const edges = bundle.writer
+            .prepare(`SELECT e.* FROM kg_edges e
+         JOIN kg_nodes n ON e.src_id = n.id
+         WHERE n.scope = ?`)
+            .all(options.scope);
+        const chunks = bundle.writer
+            .prepare(`SELECT c.* FROM kg_chunks c
+         JOIN kg_nodes n ON c.node_id = n.id
+         WHERE n.scope = ?`)
+            .all(options.scope);
+        const data = {
+            scope: options.scope,
+            exported_at: new Date().toISOString(),
+            nodes,
+            edges,
+            chunks,
+        };
+        if (options.out) {
+            writeFileSync(options.out, JSON.stringify(data, null, 2), 'utf-8');
+        }
+        return data;
+    }
+    finally {
+        closeDb(bundle);
+    }
+}
+export function renderExport(data, outPath) {
+    const line = `${data.scope}: ${data.nodes.length} nodes, ${data.edges.length} edges, ${data.chunks.length} chunks`;
+    if (outPath)
+        return `${line} → ${outPath}`;
+    return line;
+}
+// ----------------------------------------------------------------------------
+// Path helpers
+// ----------------------------------------------------------------------------
+function resolveDbPath(options, scope) {
+    if (scope === 'personal') {
+        if (options.profileDbPath)
+            return resolveAbs(options.profileDbPath);
+        const env = process.env.KG_PROFILE_PATH;
+        const profileDir = env ? resolveAbs(env) : resolve(homedir(), '.pharos/profile');
+        return resolve(profileDir, 'kg.db');
+    }
+    if (options.dbPath)
+        return resolveAbs(options.dbPath);
+    if (options.wikiPath)
+        return resolve(dirname(resolveAbs(options.wikiPath)), 'kg.db');
+    return resolve(process.cwd(), '.pharos/kg.db');
+}
+function resolveAbs(p) {
+    return isAbsolute(p) ? p : resolve(process.cwd(), p);
+}
+//# sourceMappingURL=export.js.map

package/dist/cli/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/cli/export.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAkClD,MAAM,UAAU,aAAa,CAAC,OAAsB;IAClD,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAErD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACrC,KAAK,EAAE,EAAE;YACT,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,EAAE;SACX,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM;aACxB,OAAO,CAAC,wCAAwC,CAAC;aACjD,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtB,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM;aACxB,OAAO,CACN;;2BAEmB,CACpB;aACA,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM;aACzB,OAAO,CACN;;2BAEmB,CACpB;aACA,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAEtB,MAAM,IAAI,GAAe;YACvB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACrC,KAAK;YACL,KAAK;YACL,MAAM;SACP,CAAC;QAEF,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;YAChB,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAgB,EAAE,OAAgB;IAC7D,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,KAAM,IAAI,CAAC,KAAmB,CAAC,MAAM,WAAY,IAAI,CAAC,KAAmB,CAAC,MAAM,WAAY,IAAI,CAAC,MAAoB,CAAC,MAAM,SAAS,CAAC;IAChK,IAAI,OAAO;QAAE,OAAO,GAAG,IAAI,MAAM,OAAO,EAAE,CAAC;IAC3C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E,SAAS,aAAa,CAAC,OAAsB,EAAE,KAA6B;IAC1E,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,aAAa;YAAE,OAAO,UAAU,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACpE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;QACxC,MAAM,UAAU,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,iBAAiB,CAAC,CAAC;QACjF,OAAO,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,OAAO,CAAC,MAAM;QAAE,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,OAAO,CAAC,QAAQ;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACrF,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,eAAe,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/cli/import.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `kg import --scope <s> --in file.json` — restore nodes, edges, and chunks
+ * from a JSON dump produced by `kg export`.
+ *
+ * Imports are additive: existing rows with the same PK are replaced via
+ * INSERT OR REPLACE. This makes import idempotent — running it twice
+ * with the same file produces the same DB state.
+ */
+export interface ImportOptions {
+    scope: 'project' | 'personal';
+    inFile: string;
+    dbPath?: string;
+    wikiPath?: string;
+    profileDbPath?: string;
+}
+export interface ImportResult {
+    scope: string;
+    nodes: number;
+    edges: number;
+    chunks: number;
+}
+export declare function importCommand(options: ImportOptions): ImportResult;
+export declare function renderImport(result: ImportResult): string;
+//# sourceMappingURL=import.d.ts.map

package/dist/cli/import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../src/cli/import.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAaD,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAuFlE;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAEzD"}

package/dist/cli/import.js

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { closeDb, openDb } from '../db/client.js';
+import { logger } from '../observability/logger.js';
+export function importCommand(options) {
+    if (!existsSync(options.inFile)) {
+        throw new Error(`input file does not exist: ${options.inFile}`);
+    }
+    const raw = readFileSync(options.inFile, 'utf-8');
+    const data = JSON.parse(raw);
+    if (data.scope && data.scope !== options.scope) {
+        logger.warn({ fileScope: data.scope, requestedScope: options.scope }, 'import file scope does not match requested scope');
+    }
+    const dbPath = resolveDbPath(options, options.scope);
+    const bundle = openDb(dbPath);
+    try {
+        const result = { scope: options.scope, nodes: 0, edges: 0, chunks: 0 };
+        bundle.writer.exec('BEGIN');
+        try {
+            // Import nodes
+            if (data.nodes?.length) {
+                const insertNode = bundle.writer.prepare(`INSERT OR REPLACE INTO kg_nodes
+           (id, scope, source_uri, section_path, kind, title, content, source_sha, token_count, confidence, created_at, updated_at, last_accessed_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+                for (const n of data.nodes) {
+                    insertNode.run(n.id, options.scope, n.source_uri, n.section_path, n.kind ?? 'section', n.title ?? null, n.content, n.source_sha, n.token_count ?? 0, n.confidence ?? 'extracted', n.created_at ?? Date.now(), n.updated_at ?? Date.now(), n.last_accessed_at ?? Date.now());
+                    result.nodes++;
+                }
+            }
+            // Import edges
+            if (data.edges?.length) {
+                const insertEdge = bundle.writer.prepare(`INSERT OR REPLACE INTO kg_edges (src_id, dst_id, edge_kind)
+           VALUES (?, ?, ?)`);
+                for (const e of data.edges) {
+                    try {
+                        insertEdge.run(e.src_id, e.dst_id, e.edge_kind);
+                        result.edges++;
+                    }
+                    catch (err) {
+                        // FK violations expected if referenced nodes aren't in the dump
+                        logger.debug({ err, edge: e }, 'import: skipped edge (FK violation)');
+                    }
+                }
+            }
+            // Import chunks
+            if (data.chunks?.length) {
+                const insertChunk = bundle.writer.prepare(`INSERT OR REPLACE INTO kg_chunks
+           (id, node_id, chunk_index, text, chunk_sha, token_count, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`);
+                for (const c of data.chunks) {
+                    try {
+                        insertChunk.run(c.id, c.node_id, c.chunk_index, c.text, c.chunk_sha, c.token_count ?? 0, c.created_at ?? Date.now());
+                        result.chunks++;
+                    }
+                    catch (err) {
+                        logger.debug({ err, chunk: c }, 'import: skipped chunk (FK violation)');
+                    }
+                }
+            }
+            bundle.writer.exec('COMMIT');
+        }
+        catch (err) {
+            bundle.writer.exec('ROLLBACK');
+            throw err;
+        }
+        return result;
+    }
+    finally {
+        closeDb(bundle);
+    }
+}
+export function renderImport(result) {
+    return `${result.scope}: imported ${result.nodes} nodes, ${result.edges} edges, ${result.chunks} chunks`;
+}
+// ----------------------------------------------------------------------------
+// Path helpers
+// ----------------------------------------------------------------------------
+function resolveDbPath(options, scope) {
+    if (scope === 'personal') {
+        if (options.profileDbPath)
+            return resolveAbs(options.profileDbPath);
+        const env = process.env.KG_PROFILE_PATH;
+        const profileDir = env ? resolveAbs(env) : resolve(homedir(), '.pharos/profile');
+        return resolve(profileDir, 'kg.db');
+    }
+    if (options.dbPath)
+        return resolveAbs(options.dbPath);
+    if (options.wikiPath)
+        return resolve(dirname(resolveAbs(options.wikiPath)), 'kg.db');
+    return resolve(process.cwd(), '.pharos/kg.db');
+}
+function resolveAbs(p) {
+    return isAbsolute(p) ? p : resolve(process.cwd(), p);
+}
+//# sourceMappingURL=import.js.map

package/dist/cli/import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import.js","sourceRoot":"","sources":["../../src/cli/import.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAqCpD,MAAM,UAAU,aAAa,CAAC,OAAsB;IAClD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAC;IAE3C,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO,CAAC,KAAK,EAAE,CAAC;QAC/C,MAAM,CAAC,IAAI,CACT,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,CAAC,KAAK,EAAE,EACxD,kDAAkD,CACnD,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,MAAM,GAAiB,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QAErF,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,IAAI,CAAC;YACH,eAAe;YACf,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;gBACvB,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CACtC;;0DAEgD,CACjD,CAAC;gBACF,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;oBAC3B,UAAU,CAAC,GAAG,CACZ,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,IAAI,IAAI,SAAS,EACtE,CAAC,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,WAAW,IAAI,CAAC,EAC5D,CAAC,CAAC,UAAU,IAAI,WAAW,EAAE,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE,EACvD,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,gBAAgB,IAAI,IAAI,CAAC,GAAG,EAAE,CAC7D,CAAC;oBACF,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,CAAC;YACH,CAAC;YAED,eAAe;YACf,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;gBACvB,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CACtC;4BACkB,CACnB,CAAC;gBACF,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;oBAC3B,IAAI,CAAC;wBACH,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;wBAChD,MAAM,CAAC,KAAK,EAAE,CAAC;oBACjB,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,gEAAgE;wBAChE,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,qCAAqC,CAAC,CAAC;oBACxE,CAAC;gBACH,CAAC;YACH,CAAC;YAED,gBAAgB;YAChB,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBACxB,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CACvC;;wCAE8B,CAC/B,CAAC;gBACF,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;oBAC5B,IAAI,CAAC;wBACH,WAAW,CAAC,GAAG,CACb,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,EACtC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,WAAW,IAAI,CAAC,EAAE,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE,CAC5D,CAAC;wBACF,MAAM,CAAC,MAAM,EAAE,CAAC;oBAClB,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,sCAAsC,CAAC,CAAC;oBAC1E,CAAC;gBACH,CAAC;YACH,CAAC;YAED,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,GAAG,MAAM,CAAC,KAAK,cAAc,MAAM,CAAC,KAAK,WAAW,MAAM,CAAC,KAAK,WAAW,MAAM,CAAC,MAAM,SAAS,CAAC;AAC3G,CAAC;AAED,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E,SAAS,aAAa,CAAC,OAAsB,EAAE,KAA6B;IAC1E,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,aAAa;YAAE,OAAO,UAAU,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACpE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;QACxC,MAAM,UAAU,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,iBAAiB,CAAC,CAAC;QACjF,OAAO,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,OAAO,CAAC,MAAM;QAAE,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,OAAO,CAAC,QAAQ;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACrF,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,eAAe,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}