@arkheia/mcp-server 0.1.4 → 0.1.6

package/README.md

@@ -1,89 +1,177 @@
-# Arkheia MCP Server — Fabrication Detection for AI Agents
-
-Know when your AI is making things up.
-
-Arkheia screens model responses for fabrication using behavioural fingerprinting. Works with Claude, GPT, Gemini, Grok, Llama, Mistral, and 30+ other models. One tool call. Real-time risk scoring.
-
-Free tier: 1,500 detections/month. No credit card.
-
-## Quick Start
-
-```bash
-npx @arkheia/mcp-server
-```
-
-Get a free API key:
-
-```bash
-curl -X POST https://arkheia-proxy-production.up.railway.app/v1/provision \
-  -H "Content-Type: application/json" \
-  -d '{"email": "you@example.com"}'
-```
-
-Add to your agent config (Claude Code, Claude Desktop, Cursor, or any MCP-compatible tool):
-
-```json
-{
-  "mcpServers": {
-    "arkheia": {
-      "command": "python",
-      "args": ["-m", "mcp_server.server"],
-      "cwd": "~/.arkheia/mcp",
-      "env": {
-        "PYTHONPATH": "~/.arkheia/mcp",
-        "ARKHEIA_API_KEY": "ak_live_your_key_here"
-      }
-    }
-  }
-}
-```
-
-Restart your agent. Then ask it:
-
-> "Use arkheia_verify to check this response: The Kafka 4.1 ConsumerLease API introduces a lease-based partition ownership model."
-
-It should flag this as **HIGH** risk — because the Kafka 4.1 ConsumerLease API doesn't exist.
-
-## What You Get
-
-| Tool | Description |
-|------|-------------|
-| `arkheia_verify` | Score any model response for fabrication risk (LOW/MEDIUM/HIGH) |
-| `arkheia_audit_log` | Review your detection history |
-| `run_grok` | Call Grok + screen for fabrication |
-| `run_gemini` | Call Gemini + screen for fabrication |
-| `run_ollama` | Call local Ollama model + screen |
-| `run_together` | Call Together AI (Kimi, DeepSeek) + screen |
-
-## 35+ Model Profiles
-
-GPT-4o, GPT-5.4, Claude Opus/Sonnet/Haiku, Gemini 2.5/3.0, Grok 4, Llama, Mixtral, CodeLlama, Falcon, Phi4, Kimi K2.5, and more. If your model isn't listed, [let us know](mailto:dmurfet@arkheia.ai).
-
-## Pricing
-
-| Plan | Price | Detections |
-|------|-------|------------|
-| Free | $0 | 1,500/month |
-| Single Contributor | $99/month | Unlimited |
-| Professional | $499/month | Unlimited |
-| Team | $1,999/month | Unlimited |
-
-## Full Documentation
-
-See the [GitHub repo](https://github.com/arkheiaai/arkheia-mcp) for:
-- Complete setup guide for all agents
-- CLAUDE.md template for automatic detection across projects
-- Multi-agent quorum pattern
-- Test prompts and examples
-
-## Feedback
-
-- **GitHub Issues:** https://github.com/arkheiaai/arkheia-mcp/issues
-- **Email:** dmurfet@arkheia.ai
-
-Every message is read by the founder.
-
-## Links
-
-- Website: https://arkheia.ai
-- GitHub: https://github.com/arkheiaai/arkheia-mcp
+# Arkheia MCP Server — Fabrication Detection for AI Agents
+
+Know when your AI is making things up.
+
+Arkheia screens model responses for fabrication using behavioural fingerprinting. Works with Claude, GPT, Gemini, Grok, Llama, Mistral, and 30+ other models. One tool call. Real-time risk scoring.
+
+Free tier: 1,500 detections/month. No credit card.
+
+## Prerequisites
+
+```
+Requires:
+  - Node 18+
+  - Python 3.10–3.13 with working pyexpat
+
+macOS note: Homebrew's current `brew install python` installs 3.14,
+which has a broken pyexpat link. Use `brew install python@3.12` until
+Homebrew ships a fix. Verify with:
+  python3.12 -c "import pyexpat, ensurepip"
+```
+
+## Install
+
+```bash
+npm install -g @arkheia/mcp-server
+```
+
+Get a free API key at [arkheia.ai/mcp/account](https://arkheia.ai/mcp/account), or via the CLI:
+
+```bash
+curl -X POST https://arkheia-proxy-production.up.railway.app/v1/provision \
+  -H "Content-Type: application/json" \
+  -d '{"email": "you@example.com"}'
+```
+
+Set your key:
+
+```bash
+export ARKHEIA_API_KEY="ak_live_..."
+```
+
+## Register with your CLI
+
+Each AI CLI has a slightly different `mcp add` command. Use the one that matches your tool. All assume you've installed globally with `npm install -g`.
+
+### Claude Code
+
+```bash
+claude mcp add arkheia -s user \
+  -e ARKHEIA_API_KEY="$ARKHEIA_API_KEY" \
+  -- mcp-server
+```
+
+Config lands in: `~/.claude.json` under `mcpServers.arkheia`
+
+### Codex
+
+```bash
+codex mcp add arkheia \
+  --env ARKHEIA_API_KEY="$ARKHEIA_API_KEY" \
+  -- mcp-server
+```
+
+Config lands in: `~/.codex/config.toml` under `[mcp_servers.arkheia.env]`
+
+Note: `codex login --api-key` is deprecated. Use `printenv OPENAI_API_KEY | codex login --with-api-key` instead.
+
+### Gemini
+
+```bash
+gemini mcp add -s user \
+  -e ARKHEIA_API_KEY="$ARKHEIA_API_KEY" \
+  arkheia mcp-server
+```
+
+Config lands in: `~/.gemini/settings.json` under `mcpServers.arkheia`
+
+**Gotcha:** `gemini mcp list` only shows project-scope servers. If you registered with `-s user`, verify by reading `~/.gemini/settings.json` directly.
+
+**Gotcha:** Don't use `npx -y @arkheia/mcp-server` with Gemini — the `-y` flag gets eaten by Gemini's yargs parser as `--yolo`. Use the globally-installed `mcp-server` binary directly.
+
+### Grok
+
+```bash
+grok mcp add arkheia \
+  -t stdio \
+  -c mcp-server \
+  -e ARKHEIA_API_KEY="$ARKHEIA_API_KEY"
+```
+
+Config lands in: `~/.grok/settings.json` under `mcpServers.arkheia` (note: env is nested under `transport`, unlike other CLIs)
+
+## Verify it works
+
+```bash
+# Claude Code — live connection test
+claude mcp list
+
+# Codex — shows 'enabled' (not a live check)
+codex mcp list
+
+# Grok — best: spawns the server and lists all 9 tools
+grok mcp test arkheia
+
+# Gemini — no built-in test; start a session and try the tool
+```
+
+**Important:** MCP registrations are not hot-reloaded. Restart your CLI session after running `mcp add`.
+
+## What You Get
+
+| Tool | Description |
+|------|-------------|
+| `arkheia_verify` | Score any model response for fabrication risk (LOW/MEDIUM/HIGH) |
+| `arkheia_audit_log` | Review your detection history |
+| `run_grok` | Call Grok + screen for fabrication |
+| `run_gemini` | Call Gemini + screen for fabrication |
+| `run_ollama` | Call local Ollama model + screen |
+| `run_together` | Call Together AI (Kimi, DeepSeek) + screen |
+| `memory_store` | Persistent knowledge graph — upsert entity |
+| `memory_retrieve` | Knowledge graph lookup |
+| `memory_relate` | Create relationship between entities |
+
+## 35+ Model Profiles
+
+GPT-4o, GPT-5.4, Claude Opus/Sonnet/Haiku, Gemini 2.5/3.0, Grok 4, Llama, Mixtral, CodeLlama, Falcon, Phi4, Kimi K2.5, and more. If your model isn't listed, [let us know](mailto:dmurfet@arkheia.ai).
+
+## Pricing
+
+| Plan | Price | Detections |
+|------|-------|------------|
+| Free | $0 | 1,500/month |
+| Single Contributor | $99/month | Unlimited |
+| Professional | $499/month | Unlimited |
+| Team | $1,999/month | Unlimited |
+
+Manage your account at [arkheia.ai/mcp/account](https://arkheia.ai/mcp/account).
+
+## Where API keys are stored
+
+| CLI | Config file | Key location |
+|-----|-------------|-------------|
+| Claude Code | `~/.claude.json` | `mcpServers.arkheia.env.ARKHEIA_API_KEY` |
+| Codex | `~/.codex/config.toml` | `[mcp_servers.arkheia.env]` section |
+| Gemini | `~/.gemini/settings.json` | `mcpServers.arkheia.env.ARKHEIA_API_KEY` |
+| Grok | `~/.grok/settings.json` | `mcpServers.arkheia.transport.env.ARKHEIA_API_KEY` |
+
+## Troubleshooting
+
+**"Python 3.10+ is required but not found"** — Install Python 3.12: `brew install python@3.12` (macOS) or download from [python.org](https://python.org).
+
+**"No module named pip"** — Your Python installation has broken pip (common with Python 3.14 on macOS). Delete `~/.arkheia/venv` and switch to Python 3.12: `brew install python@3.12`.
+
+**Server registered but tools not showing** — Restart your CLI session. MCP registrations are not hot-reloaded.
+
+**API key rejected** — Check for trailing whitespace or `\r` characters. If your env file was created on Windows, run `dos2unix` on it. The server will warn about this on startup.
+
+## Full Documentation
+
+See the [GitHub repo](https://github.com/arkheiaai/arkheia-mcp) for:
+- Complete setup guide for all agents
+- CLAUDE.md template for automatic detection across projects
+- Multi-agent quorum pattern
+- Test prompts and examples
+
+## Feedback
+
+- **GitHub Issues:** https://github.com/arkheiaai/arkheia-mcp/issues
+- **Email:** dmurfet@arkheia.ai
+
+Every message is read by the founder.
+
+## Links
+
+- Website: https://arkheia.ai
+- MCP Account: https://arkheia.ai/mcp/account
+- GitHub: https://github.com/arkheiaai/arkheia-mcp

package/dist/index.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const fs = __importStar(require("fs"));
+const proxy_client_js_1 = require("./proxy-client.js");
+const tool_registry_js_1 = require("./tool-registry.js");
+const providers_js_1 = require("./providers.js");
+const memory_js_1 = require("./memory.js");
+// ---------------------------------------------------------------------------
+// Config Loading
+// ---------------------------------------------------------------------------
+function loadConfig() {
+    const configPath = path.join(os.homedir(), '.arkheia', 'config.json');
+    if (!fs.existsSync(configPath))
+        return;
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (config.api_key && !process.env.ARKHEIA_API_KEY) {
+            process.env.ARKHEIA_API_KEY = config.api_key;
+            process.stderr.write(`[arkheia] API key loaded from ${configPath}\n`);
+        }
+        if (config.proxy_url && !process.env.ARKHEIA_HOSTED_URL) {
+            process.env.ARKHEIA_HOSTED_URL = config.proxy_url;
+            process.stderr.write(`[arkheia] Hosted URL: ${config.proxy_url}\n`);
+        }
+    }
+    catch (e) {
+        process.stderr.write(`[arkheia] Warning: Could not read ${configPath}\n`);
+    }
+}
+function checkCRLF() {
+    for (const k of ['ARKHEIA_API_KEY', 'ARKHEIA_PROXY_URL', 'ARKHEIA_HOSTED_URL']) {
+        const v = process.env[k];
+        if (v && /[\r\n]/.test(v)) {
+            process.stderr.write(`[arkheia] WARNING: ${k} contains whitespace/newline characters. Run 'dos2unix' on your env file.\n`);
+            process.env[k] = v.trim();
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function wrapResult(result) {
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+}
+function handleError(toolName, e) {
+    if (e instanceof tool_registry_js_1.PolicyViolation) {
+        return wrapResult({ error: e.reason, risk_level: "UNKNOWN" });
+    }
+    process.stderr.write(`[arkheia] ${toolName} error: ${e.message}\n`);
+    return wrapResult({ error: e.message, risk_level: "UNKNOWN" });
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    loadConfig();
+    checkCRLF();
+    const ARKHEIA_PROXY_URL = process.env.ARKHEIA_PROXY_URL || "http://localhost:8098";
+    const ARKHEIA_HOSTED_URL = process.env.ARKHEIA_HOSTED_URL || "https://arkheia-proxy-production.up.railway.app";
+    const ARKHEIA_API_KEY = process.env.ARKHEIA_API_KEY;
+    if (!ARKHEIA_API_KEY) {
+        process.stderr.write("[arkheia] Warning: ARKHEIA_API_KEY not set.\n" +
+            "Get a free API key at https://arkheia.ai/mcp\n" +
+            "Then set: export ARKHEIA_API_KEY=ak_live_...\n\n");
+    }
+    const proxy = new proxy_client_js_1.ProxyClient(ARKHEIA_PROXY_URL, 10.0, ARKHEIA_HOSTED_URL, ARKHEIA_API_KEY);
+    const server = new mcp_js_1.McpServer({ name: "arkheia-trust", version: "0.1.6" });
+    // ── Detection & audit ──────────────────────────────────────────
+    server.tool("arkheia_verify", "Verify whether an AI response shows signs of fabrication. Call this on EVERY model response before acting on it.", { prompt: zod_1.z.string(), response: zod_1.z.string(), model: zod_1.z.string() }, async ({ prompt, response, model }) => {
+        try {
+            (0, tool_registry_js_1.check)("arkheia_verify");
+            const result = await proxy.verify(prompt, response, model);
+            return wrapResult(result);
+        }
+        catch (e) {
+            return handleError("arkheia_verify", e);
+        }
+    });
+    server.tool("arkheia_audit_log", "Retrieve structured audit evidence for compliance review.", { session_id: zod_1.z.string().optional(), limit: zod_1.z.number().int().min(1).max(500).default(50) }, async ({ session_id, limit }) => {
+        try {
+            (0, tool_registry_js_1.check)("arkheia_audit_log");
+            const result = await proxy.get_audit_log(session_id, Math.min(limit, 500));
+            return wrapResult(result);
+        }
+        catch (e) {
+            return handleError("arkheia_audit_log", e);
+        }
+    });
+    // ── Provider wrappers ──────────────────────────────────────────
+    server.tool("run_grok", "Call xAI Grok and screen the response through Arkheia for fabrication.", { prompt: zod_1.z.string(), model: zod_1.z.string().default("grok-4-fast-non-reasoning") }, async ({ prompt, model }) => {
+        try {
+            (0, tool_registry_js_1.check)("run_grok");
+            const pr = await (0, providers_js_1.call_grok)(prompt, model);
+            if (pr.error)
+                return wrapResult({ ...pr, arkheia: { risk_level: "UNKNOWN", error: pr.error } });
+            const risk = await proxy.verify(prompt, pr.response, model);
+            return wrapResult({ ...pr, arkheia: risk });
+        }
+        catch (e) {
+            return handleError("run_grok", e);
+        }
+    });
+    server.tool("run_gemini", "Call Google Gemini and screen the response through Arkheia for fabrication.", { prompt: zod_1.z.string(), model: zod_1.z.string().default("gemini-2.5-flash") }, async ({ prompt, model }) => {
+        try {
+            (0, tool_registry_js_1.check)("run_gemini");
+            const pr = await (0, providers_js_1.call_gemini)(prompt, model);
+            if (pr.error)
+                return wrapResult({ ...pr, arkheia: { risk_level: "UNKNOWN", error: pr.error } });
+            const risk = await proxy.verify(prompt, pr.response, model);
+            return wrapResult({ ...pr, arkheia: risk });
+        }
+        catch (e) {
+            return handleError("run_gemini", e);
+        }
+    });
+    server.tool("run_ollama", "Call a local Ollama model and screen the response through Arkheia. No network egress.", { prompt: zod_1.z.string(), model: zod_1.z.string().default("phi4:14b") }, async ({ prompt, model }) => {
+        try {
+            (0, tool_registry_js_1.check)("run_ollama");
+            const pr = await (0, providers_js_1.call_ollama)(prompt, model);
+            if (pr.error)
+                return wrapResult({ ...pr, arkheia: { risk_level: "UNKNOWN", error: pr.error } });
+            const risk = await proxy.verify(prompt, pr.response, model);
+            return wrapResult({ ...pr, arkheia: risk });
+        }
+        catch (e) {
+            return handleError("run_ollama", e);
+        }
+    });
+    server.tool("run_together", "Call Together AI (Kimi K2.5, DeepSeek, etc.) and screen the response through Arkheia.", { prompt: zod_1.z.string(), model: zod_1.z.string().default("moonshotai/Kimi-K2.5") }, async ({ prompt, model }) => {
+        try {
+            (0, tool_registry_js_1.check)("run_together");
+            const pr = await (0, providers_js_1.call_together)(prompt, model);
+            if (pr.error)
+                return wrapResult({ ...pr, arkheia: { risk_level: "UNKNOWN", error: pr.error } });
+            const risk = await proxy.verify(prompt, pr.response, model);
+            return wrapResult({ ...pr, arkheia: risk });
+        }
+        catch (e) {
+            return handleError("run_together", e);
+        }
+    });
+    // ── Memory / Knowledge Graph ───────────────────────────────────
+    server.tool("memory_store", "Store an entity and its observations in the persistent knowledge graph. Entities are upserted by name+type.", { name: zod_1.z.string(), entity_type: zod_1.z.string(), observations: zod_1.z.array(zod_1.z.string()) }, async ({ name, entity_type, observations }) => {
+        try {
+            (0, tool_registry_js_1.check)("memory_store");
+            const result = await (0, memory_js_1.store_entity)(name, entity_type, observations);
+            return wrapResult(result);
+        }
+        catch (e) {
+            return handleError("memory_store", e);
+        }
+    });
+    server.tool("memory_retrieve", "Search entities in the persistent knowledge graph by name (case-insensitive).", { query: zod_1.z.string(), entity_type: zod_1.z.string().optional(), limit: zod_1.z.number().int().min(1).max(50).default(10) }, async ({ query, entity_type, limit }) => {
+        try {
+            (0, tool_registry_js_1.check)("memory_retrieve");
+            const result = await (0, memory_js_1.retrieve_entities)(query, entity_type, Math.min(limit, 50));
+            return wrapResult(result);
+        }
+        catch (e) {
+            return handleError("memory_retrieve", e);
+        }
+    });
+    server.tool("memory_relate", "Store a named relationship between two entities in the knowledge graph.", { from_entity: zod_1.z.string(), relation_type: zod_1.z.string(), to_entity: zod_1.z.string() }, async ({ from_entity, relation_type, to_entity }) => {
+        try {
+            (0, tool_registry_js_1.check)("memory_relate");
+            const result = await (0, memory_js_1.store_relation)(from_entity, relation_type, to_entity);
+            return wrapResult(result);
+        }
+        catch (e) {
+            return handleError("memory_relate", e);
+        }
+    });
+    // ── Start ──────────────────────────────────────────────────────
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`[arkheia] Fatal error: ${err}\n`);
+    process.exit(1);
+});

package/dist/memory.js

@@ -0,0 +1,187 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.store_entity = store_entity;
+exports.retrieve_entities = retrieve_entities;
+exports.store_relation = store_relation;
+const sql_js_1 = __importDefault(require("sql.js"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const crypto = __importStar(require("crypto"));
+const os = __importStar(require("os"));
+const logger = console;
+// ---------------------------------------------------------------------------
+// DB setup — sql.js (pure JS, no native module)
+// ---------------------------------------------------------------------------
+function _db_path() {
+    return process.env.MEMORY_DB_PATH || path.join(os.homedir(), '.arkheia', 'memory.db');
+}
+let _db = null;
+let _dbReady = null;
+function _getDb() {
+    if (_dbReady)
+        return _dbReady;
+    _dbReady = (async () => {
+        const SQL = await (0, sql_js_1.default)();
+        const dbPath = _db_path();
+        const dir = path.dirname(dbPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // Load existing DB or create new
+        if (fs.existsSync(dbPath)) {
+            const buffer = fs.readFileSync(dbPath);
+            _db = new SQL.Database(buffer);
+        }
+        else {
+            _db = new SQL.Database();
+        }
+        // Init schema
+        _db.run(`
+            CREATE TABLE IF NOT EXISTS entities (
+                entity_id   TEXT PRIMARY KEY,
+                name        TEXT NOT NULL,
+                entity_type TEXT NOT NULL,
+                created_at  TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS observations (
+                obs_id      TEXT PRIMARY KEY,
+                entity_id   TEXT NOT NULL REFERENCES entities(entity_id),
+                content     TEXT NOT NULL,
+                created_at  TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS relations (
+                rel_id        TEXT PRIMARY KEY,
+                from_entity   TEXT NOT NULL,
+                relation_type TEXT NOT NULL,
+                to_entity     TEXT NOT NULL,
+                created_at    TEXT NOT NULL
+            );
+        `);
+        _save(_db);
+        return _db;
+    })();
+    return _dbReady;
+}
+function _save(db) {
+    const data = db.export();
+    const buffer = Buffer.from(data);
+    fs.writeFileSync(_db_path(), buffer);
+}
+// ---------------------------------------------------------------------------
+// Public functions
+// ---------------------------------------------------------------------------
+async function store_entity(name, entity_type, observations) {
+    const db = await _getDb();
+    const now = new Date().toISOString();
+    // Upsert entity — look up by name+type
+    let entity_id;
+    const existing = db.exec("SELECT entity_id FROM entities WHERE name = ? AND entity_type = ?", [name, entity_type]);
+    if (existing.length > 0 && existing[0].values.length > 0) {
+        entity_id = existing[0].values[0][0];
+    }
+    else {
+        entity_id = crypto.randomUUID();
+        db.run("INSERT INTO entities (entity_id, name, entity_type, created_at) VALUES (?, ?, ?, ?)", [entity_id, name, entity_type, now]);
+    }
+    // Fetch existing observation contents to deduplicate
+    const existingObs = db.exec("SELECT content FROM observations WHERE entity_id = ?", [entity_id]);
+    const existingContentSet = new Set();
+    if (existingObs.length > 0) {
+        for (const row of existingObs[0].values) {
+            existingContentSet.add(row[0]);
+        }
+    }
+    let added = 0;
+    for (const content of observations) {
+        if (!existingContentSet.has(content)) {
+            db.run("INSERT INTO observations (obs_id, entity_id, content, created_at) VALUES (?, ?, ?, ?)", [crypto.randomUUID(), entity_id, content, now]);
+            existingContentSet.add(content);
+            added++;
+        }
+    }
+    const countResult = db.exec("SELECT COUNT(*) AS n FROM observations WHERE entity_id = ?", [entity_id]);
+    const totalObservations = countResult.length > 0 ? countResult[0].values[0][0] : 0;
+    _save(db);
+    return {
+        entity_id,
+        name,
+        entity_type,
+        observations_added: added,
+        total_observations: totalObservations,
+    };
+}
+async function retrieve_entities(query, entity_type = undefined, limit = 10) {
+    const db = await _getDb();
+    const pattern = `%${query}%`;
+    let rows;
+    if (entity_type) {
+        const result = db.exec("SELECT entity_id, name, entity_type, created_at FROM entities WHERE name LIKE ? AND entity_type = ?", [pattern, entity_type]);
+        rows = result.length > 0 ? result[0].values.map(r => ({ entity_id: r[0], name: r[1], entity_type: r[2], created_at: r[3] })) : [];
+    }
+    else {
+        const result = db.exec("SELECT entity_id, name, entity_type, created_at FROM entities WHERE name LIKE ?", [pattern]);
+        rows = result.length > 0 ? result[0].values.map(r => ({ entity_id: r[0], name: r[1], entity_type: r[2], created_at: r[3] })) : [];
+    }
+    const total = rows.length;
+    rows = rows.slice(0, Math.min(limit, 50));
+    const entities = [];
+    for (const row of rows) {
+        const obsResult = db.exec("SELECT content, created_at FROM observations WHERE entity_id = ? ORDER BY created_at", [row.entity_id]);
+        const obs = obsResult.length > 0 ? obsResult[0].values.map(o => ({ content: o[0], created_at: o[1] })) : [];
+        const relResult = db.exec("SELECT relation_type, to_entity FROM relations WHERE from_entity = ? ORDER BY created_at", [row.name]);
+        const rels = relResult.length > 0 ? relResult[0].values.map(r => ({ relation_type: r[0], to_entity: r[1] })) : [];
+        entities.push({
+            entity_id: row.entity_id,
+            name: row.name,
+            entity_type: row.entity_type,
+            created_at: row.created_at,
+            observations: obs,
+            relations: rels,
+        });
+    }
+    return { entities, total };
+}
+async function store_relation(from_entity, relation_type, to_entity) {
+    const db = await _getDb();
+    const rel_id = crypto.randomUUID();
+    const now = new Date().toISOString();
+    db.run("INSERT INTO relations (rel_id, from_entity, relation_type, to_entity, created_at) VALUES (?, ?, ?, ?, ?)", [rel_id, from_entity, relation_type, to_entity, now]);
+    _save(db);
+    return { rel_id, from_entity, relation_type, to_entity };
+}