tokenos 1.1.0

package/USAGE.md

@@ -0,0 +1,451 @@
+# How to Use TokenOS — Token-Saving Guide
+
+> **Problem**: Every new AI chat session analyzes your entire codebase from scratch — reading dozens of files, burning thousands of tokens, and wasting compute before any real work begins.
+>
+> **Solution**: TokenOS pre-indexes your codebase into a structured graph. The AI queries the graph to get exactly the context it needs in 1–2 tool calls instead of scanning every file.
+
+---
+
+## Table of Contents
+
+1. [Setup (One-Time)](#1-setup-one-time)
+2. [How It Saves Tokens](#2-how-it-saves-tokens)
+3. [Real-World Workflows](#3-real-world-workflows)
+4. [Tool-by-Tool Usage Guide](#4-tool-by-tool-usage-guide)
+5. [Tips for Maximum Token Savings](#5-tips-for-maximum-token-savings)
+6. [Adding to Your Project](#6-adding-to-your-project)
+7. [Troubleshooting](#7-troubleshooting)
+
+---
+
+## 1. Setup (One-Time)
+
+### Step 1: Configure your project path
+
+Edit `tokenos.config.json` in the TokenOS directory:
+
+```json
+{
+  "watchPath": "/Users/wripcode_/Desktop/myLab/swiss-knife-flow",
+  "ollama": {
+    "url": "http://localhost:11434",
+    "model": "mxbai-embed-large:latest"
+  }
+}
+```
+
+### Step 2: Start the server
+
+```bash
+cd /path/to/TokenOS
+npm run dev
+```
+
+The server indexes your codebase once, then watches for changes. It stays running in the background.
+
+### Step 3: Connect your AI client
+
+Add to your MCP client config (Claude Desktop, Cursor, etc.):
+
+```json
+{
+  "mcpServers": {
+    "tokenos": {
+      "command": "npx",
+      "args": ["tsx", "/absolute/path/to/TokenOS/src/main.ts"]
+    }
+  }
+}
+```
+
+**That's it.** The AI now has access to 6 query tools instead of scanning files.
+
+---
+
+## 2. How It Saves Tokens
+
+### Without TokenOS (the old way)
+
+```
+You: "Add a new auth middleware to swiss-knife-flow"
+
+AI: Let me understand your codebase...
+  → list_dir src/ (50 files)
+  → view_file src/app/layout.tsx
+  → view_file src/middleware.ts
+  → view_file src/lib/auth.ts
+  → view_file src/app/api/auth/route.ts
+  → view_file src/components/auth-provider.tsx
+  → view_file src/types/auth.ts
+  → grep_search "middleware" (30 results)
+  → view_file ... (3 more files)
+  
+Total: ~10-15 tool calls, ~8,000-15,000 tokens just to understand the codebase
+```
+
+### With TokenOS (the new way)
+
+```
+You: "Add a new auth middleware to swiss-knife-flow"
+
+AI: Let me find the relevant code...
+  → find_nodes { query: "auth middleware", mode: "semantic" }
+  → get_connections { id: "src/middleware.ts::middleware" }
+  
+Total: 2 tool calls, ~500-1,000 tokens to understand the relevant parts
+```
+
+**Result: 80-95% token reduction for codebase understanding.**
+
+---
+
+## 3. Real-World Workflows
+
+### Scenario 1: Implementing a New Function
+
+> *"I want to add a `validateWebhook()` function to my swiss-knife-flow project"*
+
+**What the AI should do:**
+
+1. **Find related code** (1 tool call):
+   ```
+   find_nodes { query: "webhook validate", mode: "semantic" }
+   ```
+   → Returns existing webhook-related functions, their file paths, and importance scores.
+
+2. **Understand the context** (1 tool call):
+   ```
+   get_connections { id: "src/lib/webhooks.ts::processWebhook" }
+   ```
+   → Shows what calls `processWebhook`, what it imports, and related types.
+
+3. **Now implement** — The AI knows exactly where to put the new function and what patterns to follow, without reading every file.
+
+**Tokens saved**: ~5,000–10,000
+
+---
+
+### Scenario 2: Debugging an Issue
+
+> *"The login flow is broken after the last refactor"*
+
+**What the AI should do:**
+
+1. **Find the entry point** (1 tool call):
+   ```
+   find_nodes { query: "login", type: "function" }
+   ```
+
+2. **Trace the call graph** (1 tool call):
+   ```
+   explore { id: "src/app/api/auth/login/route.ts::POST", depth: 2 }
+   ```
+   → Shows the full call chain: route → auth service → database → response.
+
+3. **Read only the relevant files** — Now the AI reads 2–3 specific files instead of scanning 50.
+
+---
+
+### Scenario 3: Understanding Unfamiliar Code
+
+> *"What are the most important parts of this codebase?"*
+
+**What the AI should do:**
+
+1. **Get the architecture overview** (1 tool call):
+   ```
+   top_nodes { limit: 15 }
+   ```
+   → Returns the 15 most connected/important nodes — the backbone of your app.
+
+2. **Drill into specific areas** as needed:
+   ```
+   get_connections { id: "src/lib/api-client.ts::ApiClient" }
+   ```
+
+---
+
+### Scenario 4: Adding a Feature That Touches Multiple Files
+
+> *"Add dark mode support to the dashboard"*
+
+**What the AI should do:**
+
+1. **Find all UI-related code** (1 tool call):
+   ```
+   find_nodes { query: "theme color style", mode: "semantic", type: "variable" }
+   ```
+
+2. **Find the component tree** (1 tool call):
+   ```
+   find_nodes { query: "dashboard", type: "function" }
+   ```
+
+3. **Trace dependencies** (1 tool call per key component):
+   ```
+   get_connections { id: "src/components/dashboard/layout.tsx::DashboardLayout" }
+   ```
+
+---
+
+### Scenario 5: Refactoring
+
+> *"Rename the `fetchSites` function and update all callers"*
+
+**What the AI should do:**
+
+1. **Find the function** (1 tool call):
+   ```
+   find_nodes { query: "fetchSites", type: "function" }
+   ```
+
+2. **Find all callers** (1 tool call):
+   ```
+   get_connections { id: "src/lib/webflow.ts::fetchSites" }
+   ```
+   → Shows every file that CALLS this function — no grep needed.
+
+---
+
+## 4. Tool-by-Tool Usage Guide
+
+### `top_nodes` — Start Here
+
+**When**: Beginning of any new conversation about the codebase.
+
+```
+top_nodes { limit: 20, response_format: "markdown" }
+```
+
+Returns the most architecturally significant nodes. This gives the AI a mental map of your project in one call. **Always start here.**
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `limit` | 20 | How many nodes (1–100) |
+| `response_format` | json | `json` or `markdown` |
+
+---
+
+### `find_nodes` — Find Relevant Code
+
+**When**: Looking for specific functions, classes, or concepts.
+
+**Text mode** (fast, name-based):
+```
+find_nodes { query: "auth", type: "function" }
+```
+Finds functions with "auth" in the name. Use `type` to narrow results.
+
+**Semantic mode** (concept-based, requires Ollama):
+```
+find_nodes { query: "user authentication handler", mode: "semantic" }
+```
+Finds code related to the concept even if the name doesn't match. E.g., `loginUser()` matches "authentication handler".
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `query` | required | Search term or description |
+| `type` | all | `function`, `class`, `file`, `import`, `variable` |
+| `mode` | text | `text` or `semantic` |
+| `limit` | 10 | Results per page (1–50) |
+| `offset` | 0 | For pagination |
+
+---
+
+### `get_node` — Full Details
+
+**When**: You have a node ID and want the complete picture (code snippet, importance, etc.).
+
+```
+get_node { id: "src/lib/auth.ts::validateToken" }
+```
+
+Returns: name, type, file path, code snippet (first 12 lines), importance score.
+
+---
+
+### `get_connections` — What's Connected?
+
+**When**: Understanding what a function calls, what calls it, and what it imports.
+
+```
+get_connections { id: "src/lib/auth.ts::validateToken" }
+```
+
+Returns:
+- **Edges**: `CALLS`, `IMPORTS`, `EXPORTS`, `EXTENDS`, `DEFINES`
+- **Connected nodes**: sorted by importance
+
+This is the key tool for understanding how code fits together without reading entire files.
+
+---
+
+### `explore` — Full Context Tree
+
+**When**: You need the complete call/dependency tree around a node.
+
+```
+explore { id: "src/app/api/route.ts::handler", depth: 2 }
+```
+
+Returns a BFS traversal — all nodes and edges reachable within `depth` hops. Use `depth: 1` for large codebases to keep responses small.
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `id` | required | Starting node |
+| `depth` | 2 | 1–3 hops |
+
+---
+
+### `search` — Smart Search
+
+**When**: You want the AI to automatically figure out the best search strategy.
+
+```
+search { query: "how does the auth flow work?", response_format: "markdown" }
+```
+
+Automatically detects intent, runs hybrid search, expands the graph, and includes relevant memories. Best for complex or exploratory queries.
+
+---
+
+## 5. Tips for Maximum Token Savings
+
+### DO ✅
+
+- **Start every new chat with `top_nodes`** — gives the AI instant context
+- **Use `type` filters** — `find_nodes { query: "auth", type: "function" }` returns only functions, not imports
+- **Use semantic search for vague queries** — "error handling" finds `catchApiError()`, `handleException()`, etc.
+- **Use `get_connections` before reading files** — often the edge list is enough to understand relationships
+- **Use `response_format: "markdown"`** — more compact for AI consumption
+
+### DON'T ❌
+
+- **Don't let the AI `list_dir` and `view_file` to "understand the codebase"** — TokenOS already has this information
+- **Don't use `depth: 3` on `explore`** — the response can be huge. Start with `depth: 1`
+- **Don't search without filters** — `find_nodes { query: "a" }` returns too many results
+- **Don't re-index manually** — the file watcher handles changes automatically
+
+### Pro Tips 💡
+
+1. **Node IDs are `filePath::name`** — e.g., `src/lib/auth.ts::validateToken`. You can construct these from file paths you already know.
+
+2. **Importance score tells priority** — Higher score = more central to the architecture. Focus on high-importance nodes first.
+
+3. **Semantic search finds concepts** — If you're looking for "the function that handles form submissions" but don't know its name, semantic mode will find it.
+
+4. **The graph updates in real-time** — When you save a file, the watcher re-indexes it. Next query will have the latest data.
+
+5. **Combine tools in sequence**:
+   ```
+   1. top_nodes { limit: 10 }                       → overview
+   2. find_nodes { query: "..." }                    → find specific code
+   3. get_connections { id: "..." }                   → understand connections
+   4. view_file (only the specific file you need)    → read actual code
+   ```
+
+---
+
+## 6. Adding to Your Project
+
+### Add `.tokenos/` to your project's `.gitignore`:
+
+```bash
+echo ".tokenos/" >> /path/to/your/project/.gitignore
+```
+
+This prevents the per-project database from being committed.
+
+### Switching Between Projects
+
+Edit `tokenos.config.json` and change `watchPath`:
+
+```json
+{
+  "watchPath": "/path/to/different/project"
+}
+```
+
+Then restart: `npm run dev`. Or if you want a fresh index:
+
+```bash
+npm run reset
+npm run dev
+```
+
+### Changing the Embedding Model
+
+Edit `tokenos.config.json`:
+
+```json
+{
+  "ollama": {
+    "model": "nomic-embed-text"
+  }
+}
+```
+
+**Important**: After changing models, run `npm run reset` then `npm run dev` — different models produce incompatible vectors.
+
+---
+
+## 7. Troubleshooting
+
+### "0 files indexed"
+
+- Check that `watchPath` points to a directory containing `.ts` or `.tsx` files
+- Check that the path exists and is accessible
+- Check `.gitignore` — files matching gitignore patterns are skipped
+
+### "Embeddings skipped (Ollama offline)"
+
+- Start Ollama: `ollama serve`
+- Pull the model: `ollama pull mxbai-embed-large:latest`
+- Semantic search falls back to text mode when Ollama is offline — everything else still works
+
+### "Semantic search returns no results"
+
+- Make sure embeddings were generated (check the boot log for "embeddings ready: X updated")
+- If you changed the model, run `npm run reset` and re-index
+
+### Stale data after refactoring
+
+```bash
+npm run reset    # delete the database
+npm run dev      # re-index from scratch
+```
+
+---
+
+## Quick Reference Card
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    TOKENOS CHEAT SHEET                        │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  START HERE:                                                 │
+│  top_nodes { limit: 15 }                                     │
+│                                                              │
+│  FIND CODE:                                                  │
+│  find_nodes { query: "auth", type: "function" }              │
+│  find_nodes { query: "handles login", mode: "semantic" }     │
+│                                                              │
+│  UNDERSTAND CONNECTIONS:                                     │
+│  get_connections { id: "file::name" }                        │
+│                                                              │
+│  EXPLORE CONTEXT:                                            │
+│  explore { id: "file::name", depth: 1 }                     │
+│                                                              │
+│  FULL NODE DETAILS:                                          │
+│  get_node { id: "file::name" }                               │
+│                                                              │
+│  SMART SEARCH:                                               │
+│  search { query: "how does auth work?" }                     │
+│                                                              │
+│  COMMANDS:                                                   │
+│  npm run dev     → start server                              │
+│  npm run reset   → delete DB & re-index                      │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Config loader for TokenOS.
+ *
+ * Precedence: CLI args → config file → env vars → defaults.
+ * Config file: tokenos.config.json in the project root.
+ */
+export interface TokenOSConfig {
+    watchPath: string;
+    ollama: {
+        url: string;
+        model: string;
+    };
+    ui: {
+        enabled: boolean;
+        port: number;
+    };
+    /** Derived: absolute path to the SQLite DB for the target project */
+    dbPath: string;
+}
+/** Singleton config — built once on import */
+export declare const config: TokenOSConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE;QACN,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,EAAE,EAAE;QACF,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;CAChB;AA+DD,8CAA8C;AAC9C,eAAO,MAAM,MAAM,EAAE,aAA6B,CAAC"}

package/dist/config.js

@@ -0,0 +1,60 @@
+/**
+ * Config loader for TokenOS.
+ *
+ * Precedence: CLI args → config file → env vars → defaults.
+ * Config file: tokenos.config.json in the project root.
+ */
+import { readFileSync, existsSync } from "fs";
+import { resolve, join, dirname } from "path";
+import { fileURLToPath } from "url";
+// ───── Loader ─────────────────────────────────────────────────────────────────
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = resolve(__dirname, "..");
+function loadConfigFile() {
+    const configPath = join(PROJECT_ROOT, "tokenos.config.json");
+    if (!existsSync(configPath))
+        return {};
+    try {
+        const raw = readFileSync(configPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+function buildConfig() {
+    const file = loadConfigFile();
+    const fileOllama = (file.ollama ?? {});
+    const fileUI = (file.ui ?? {});
+    // CLI args (backwards-compatible: first non-flag arg is watchPath, --ui flag)
+    const args = process.argv.slice(2);
+    const cliPath = args.find((a) => !a.startsWith("--"));
+    const cliUI = args.includes("--ui");
+    // Resolve watchPath: CLI > config > cwd
+    const rawPath = cliPath ?? file.watchPath ?? process.cwd();
+    const watchPath = resolve(rawPath);
+    // Ollama settings: env > config > defaults
+    const ollamaUrl = process.env.OLLAMA_URL ??
+        fileOllama.url ??
+        "http://localhost:11434";
+    const ollamaModel = process.env.EMBEDDING_MODEL ??
+        fileOllama.model ??
+        "nomic-embed-text";
+    // UI settings: CLI flag > config > defaults
+    const uiEnabled = cliUI || fileUI.enabled === true;
+    const uiPort = Number(process.env.GRAPH_UI_PORT) ||
+        fileUI.port ||
+        3333;
+    // Per-project DB: <watchPath>/.tokenos/graph.db
+    const dbPath = join(watchPath, ".tokenos", "graph.db");
+    return {
+        watchPath,
+        ollama: { url: ollamaUrl, model: ollamaModel },
+        ui: { enabled: uiEnabled, port: uiPort },
+        dbPath,
+    };
+}
+/** Singleton config — built once on import */
+export const config = buildConfig();
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAkBpC,iFAAiF;AAEjF,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AACtC,MAAM,YAAY,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAE9C,SAAS,cAAc;IACrB,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,EAAE,qBAAqB,CAAC,CAAC;IAC7D,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,WAAW;IAClB,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAA4B,CAAC;IAClE,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAA4B,CAAC;IAE1D,8EAA8E;IAC9E,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEpC,wCAAwC;IACxC,MAAM,OAAO,GAAG,OAAO,IAAK,IAAI,CAAC,SAAgC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACnF,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC,2CAA2C;IAC3C,MAAM,SAAS,GACb,OAAO,CAAC,GAAG,CAAC,UAAU;QACrB,UAAU,CAAC,GAA0B;QACtC,wBAAwB,CAAC;IAE3B,MAAM,WAAW,GACf,OAAO,CAAC,GAAG,CAAC,eAAe;QAC1B,UAAU,CAAC,KAA4B;QACxC,kBAAkB,CAAC;IAErB,4CAA4C;IAC5C,MAAM,SAAS,GAAG,KAAK,IAAK,MAAM,CAAC,OAA+B,KAAK,IAAI,CAAC;IAC5E,MAAM,MAAM,GACV,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QAChC,MAAM,CAAC,IAA2B;QACnC,IAAI,CAAC;IAEP,gDAAgD;IAChD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IAEvD,OAAO;QACL,SAAS;QACT,MAAM,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE;QAC9C,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE;QACxC,MAAM;KACP,CAAC;AACJ,CAAC;AAED,8CAA8C;AAC9C,MAAM,CAAC,MAAM,MAAM,GAAkB,WAAW,EAAE,CAAC"}

package/dist/db/connection.d.ts

@@ -0,0 +1,3 @@
+import { type Database as DatabaseType } from "better-sqlite3";
+export declare const db: DatabaseType;
+//# sourceMappingURL=connection.d.ts.map

package/dist/db/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/db/connection.ts"],"names":[],"mappings":"AAAA,OAAiB,EAAE,KAAK,QAAQ,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AASzE,eAAO,MAAM,EAAE,EAAE,YAA0C,CAAC"}

package/dist/db/connection.js

@@ -0,0 +1,78 @@
+import Database from "better-sqlite3";
+import { dirname } from "path";
+import { mkdirSync } from "fs";
+import { config } from "../config.js";
+// Ensure the .tokenos directory exists in the target project
+mkdirSync(dirname(config.dbPath), { recursive: true });
+// Open or create the SQLite database at the per-project path
+export const db = new Database(config.dbPath);
+// Enable WAL mode for better concurrent read performance
+db.pragma("journal_mode = WAL");
+db.pragma("foreign_keys = ON");
+// Run schema migrations on startup
+db.exec(`
+  -- NODES TABLE
+  CREATE TABLE IF NOT EXISTS nodes (
+    id          TEXT PRIMARY KEY,
+    type        TEXT NOT NULL,
+    name        TEXT NOT NULL,
+    file_path   TEXT NOT NULL,
+
+    summary     TEXT,
+    code_snippet TEXT,
+    embedding   TEXT,
+
+    hash        TEXT,
+    importance  REAL DEFAULT 0,
+
+    created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at  DATETIME DEFAULT CURRENT_TIMESTAMP
+  );
+
+  -- EDGES TABLE
+  CREATE TABLE IF NOT EXISTS edges (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    from_node   TEXT NOT NULL,
+    to_node     TEXT NOT NULL,
+    type        TEXT NOT NULL,
+
+    FOREIGN KEY(from_node) REFERENCES nodes(id) ON DELETE CASCADE,
+    FOREIGN KEY(to_node)   REFERENCES nodes(id) ON DELETE CASCADE
+  );
+
+  -- MEMORIES TABLE (Phase 5)
+  CREATE TABLE IF NOT EXISTS memories (
+    id          TEXT PRIMARY KEY,
+    title       TEXT NOT NULL,
+    summary     TEXT NOT NULL,
+    key_points  TEXT NOT NULL,   -- JSON array of strings
+    tags        TEXT NOT NULL,   -- JSON array of strings
+    embedding   TEXT,            -- JSON array of numbers
+    created_at  INTEGER NOT NULL
+  );
+
+  -- INDEXES
+  CREATE INDEX IF NOT EXISTS idx_nodes_name     ON nodes(name);
+  CREATE INDEX IF NOT EXISTS idx_nodes_type     ON nodes(type);
+  CREATE INDEX IF NOT EXISTS idx_nodes_file     ON nodes(file_path);
+  CREATE INDEX IF NOT EXISTS idx_nodes_importance ON nodes(importance);
+
+  CREATE INDEX IF NOT EXISTS idx_edges_from     ON edges(from_node);
+  CREATE INDEX IF NOT EXISTS idx_edges_to       ON edges(to_node);
+  CREATE INDEX IF NOT EXISTS idx_edges_type     ON edges(type);
+`);
+// ── Safe migration: add meta column if not already present ────────────────────
+try {
+    db.exec(`ALTER TABLE nodes ADD COLUMN meta TEXT;`);
+}
+catch {
+    // Column already exists — ignore
+}
+// Unique edge constraint to prevent duplicates
+try {
+    db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_edges_unique ON edges(from_node, to_node, type);`);
+}
+catch {
+    // Already exists — ignore
+}
+//# sourceMappingURL=connection.js.map

package/dist/db/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/db/connection.ts"],"names":[],"mappings":"AAAA,OAAO,QAA2C,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,6DAA6D;AAC7D,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAEvD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,EAAE,GAAiB,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAE5D,yDAAyD;AACzD,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAChC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAE/B,mCAAmC;AACnC,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDP,CAAC,CAAC;AAEH,iFAAiF;AACjF,IAAI,CAAC;IACH,EAAE,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;AACrD,CAAC;AAAC,MAAM,CAAC;IACP,iCAAiC;AACnC,CAAC;AAED,+CAA+C;AAC/C,IAAI,CAAC;IACH,EAAE,CAAC,IAAI,CAAC,wFAAwF,CAAC,CAAC;AACpG,CAAC;AAAC,MAAM,CAAC;IACP,0BAA0B;AAC5B,CAAC"}

package/dist/db/index.d.ts

@@ -0,0 +1,4 @@
+export { db } from "./connection.js";
+export * from "./queries.js";
+export * from "./memory.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/db/index.js

@@ -0,0 +1,4 @@
+export { db } from "./connection.js";
+export * from "./queries.js";
+export * from "./memory.js";
+//# sourceMappingURL=index.js.map

package/dist/db/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/db/memory.d.ts

@@ -0,0 +1,6 @@
+import type { ConversationMemory } from "../types.js";
+export declare function upsertMemory(m: ConversationMemory): void;
+export declare function getMemory(id: string): ConversationMemory | undefined;
+export declare function getAllMemories(): ConversationMemory[];
+export declare function searchMemories(query: string): ConversationMemory[];
+//# sourceMappingURL=memory.d.ts.map

package/dist/db/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/db/memory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAatD,wBAAgB,YAAY,CAAC,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAUxD;AAMD,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CASpE;AAMD,wBAAgB,cAAc,IAAI,kBAAkB,EAAE,CAOrD;AAQD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAQlE"}