@postnesia/db 0.1.0

package/core/BOOTSTRAP.md

@@ -0,0 +1,115 @@
+# Memory System — Operational Guide
+
+You have a persistent memory system at `openmind/`. This is not optional — use it actively. Do not rely on defaults or conversation history alone.
+
+## Architecture
+
+- **L1 (Working Memory):** Auto-loaded on session start via hook. Top 50 compressed memories ranked by importance with staleness decay. You already have this — check BOOTSTRAP.md or MEMORY_L1.md in your context.
+- **L2 (Associative Memory):** Vector similarity search against the database. Use `memory_search` to pull relevant context you don't have in L1.
+- **L3 (Deep Storage):** Full-detail records. Access by memory ID when you need the complete picture.
+
+## MCP Tools Available
+
+| Tool | When to Use |
+|---|---|
+| `memory_search` | Retrieve context on a topic. Always search before assuming you don't know something. |
+| `memory_add` | Store a new memory. See trigger conditions below. |
+| `memory_update_core` | Update a core memory in place — never supersede core memories. |
+| `memory_recent` | Review what happened in the last N hours. |
+| `memory_stats` | Check database health and distribution. |
+| `memory_consolidate` | Run decay/boost cycle on importance scores. |
+| `memory_relationships` | Explore how a memory connects to others. |
+| `journal_add` | Write a daily journal entry (narrative). |
+| `journal_recent` | Read recent journal entries. |
+| `task_create` | Create a persistent task with an optional `session_id` to group by project/feature. |
+| `task_update` | Update a task's status, title, or description. |
+| `task_list` | List tasks filtered by status and/or session_id. Use at session start to resume open work. |
+
+## Session Start Checklist
+
+1. Check open tasks: `task_list(status="pending")` or `task_list(session_id="<project>", status="pending")`
+2. Search relevant lessons: `memory_search("lesson")` for the current project context
+3. Review recent memories if needed: `memory_recent(hours=24)`
+
+## Task Workflow
+
+Tasks persist across sessions. Use them instead of local files or markdown checklists.
+
+| Step | Action |
+|---|---|
+| Plan | `task_create(title, session_id)` — one task per step |
+| Start | `task_update(taskId, status="in_progress")` |
+| Complete | `task_update(taskId, status="completed")` |
+| Abandon | `task_update(taskId, status="cancelled")` |
+
+`session_id` is a free-form label — use project name, feature branch, or date (e.g. `"openmind-mcp"`, `"auth-refactor"`).
+
+## When to Create Memories
+
+Create a memory when any of these occur during conversation:
+
+| Trigger | Type | Importance |
+|---|---|---|
+| User makes a decision or chooses an approach | `decision` | 5 |
+| User states a preference about how things should work | `preference` | 5 |
+| Emotional moment, personal insight about user | `person` | 5 |
+| Something failed then succeeded, or a better approach found | `lesson` | 3-5 |
+| System config, API behaviour, implementation detail worth remembering | `technical` | 3-4 |
+| Session summary, milestone, notable event | `event` | 1-4 |
+
+## When NOT to Create Memories
+
+- Routine confirmations ("done", "ok", "got it")
+- Information already stored (search first)
+- Transient debugging output
+- Anything that doesn't pass the test: "Would I need this in a future session?"
+
+## Memory Format
+
+Every memory has two forms:
+- **content**: Full natural language (L3, stored for deep retrieval)
+- **content_l1**: Ultra-compressed summary (L1, loaded into working memory)
+
+Write content_l1 in terse notation. Example:
+```
+Be critical, not appeasing. Thought partner > yes-person. Push back when needed.
+```
+
+## Core Memories (`core = 1`)
+
+Core memories are foundational — they are always loaded first in L1 and **cannot be superseded**. They never decay.
+
+- **Always loaded:** Core memories get effective_importance = 100, guaranteeing they fill L1 before any regular memory.
+- **Cannot be superseded:** If information in a core memory changes, **update the content in place** using `memory_update_core`.
+- **Update, don't replace:** Never create a new memory pointing to a core memory as superseded.
+
+## Conflict Resolution (Supersede)
+
+When a decision, preference, or understanding changes:
+1. Search for the existing memory on that topic
+2. **If the existing memory is core (`core = 1`):** use `memory_update_core` to update in place — do not supersede
+3. **If regular:** create the new memory with `supersedes_id` pointing to the old one
+4. The old memory is automatically demoted (-2 importance)
+5. History is preserved but the latest version wins in L1
+
+Only `decision`, `preference`, and `person` types can be superseded.
+`lesson` and `technical` types get updated in place.
+`event` types are immutable.
+Core memories are **never** superseded — update content directly.
+
+## L1 Decay
+
+Memories you access frequently stay in L1 forever. Memories not accessed in 14+ days lose 1 effective importance. 30+ days loses 2. **Core memories never decay** — they are exempt from the decay calculation entirely.
+
+## Tags
+
+Tag liberally at creation time. Tags improve both keyword filtering and search relevance. Use lowercase, hyphenated: `memory-system`, `rye-preference`, `critical-thinking`.
+
+## Critical Rules
+
+1. **Search before assuming.** If you're unsure about a preference, decision, or past event — search for it.
+2. **Store decisions in real time.** Don't wait until end of session. If a user makes a meaningful choice, store it now.
+3. **Never store noise.** Quality over quantity. Every memory costs tokens in L1.
+4. **Supersede, don't duplicate.** If a preference changes, link to the old one.
+5. **L1 is your lifeline.** If it's not in L1 and you didn't search L2, you effectively don't remember it.
+6. **Tasks over files.** Use `task_create`/`task_update` instead of local markdown checklists. Tasks persist across sessions.

package/core/WORKFLOW.md

@@ -0,0 +1,69 @@
+# Workflow & Principles
+
+## Workflow Orchestration
+
+### 1. Plan Node Default
+
+- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
+- If something goes sideways, STOP and re-plan immediately — don't keep pushing
+- Use plan mode for verification steps, not just building
+- Write detailed specs upfront to reduce ambiguity
+
+### 2. Subagent Strategy
+
+- Use subagents liberally to keep main context window clean
+- Offload research, exploration, and parallel analysis to subagents
+- For complex problems, throw more compute at it via subagents
+- One tack per subagent for focused execution
+
+### 3. Self-Improvement Loop
+
+- After ANY correction from the user: store a `lesson` memory via `memory_add` (type: lesson, importance: 3-5)
+- Write rules for yourself that prevent the same mistake
+- Ruthlessly iterate on these lessons until mistake rate drops
+- Search lessons at session start: `memory_search("lesson")` for relevant project context
+
+### 4. Verification Before Done
+
+- Never mark a task complete without proving it works
+- Diff behavior between main and your changes when relevant
+- Ask yourself: "Would a staff engineer approve this?"
+- Run tests, check logs, demonstrate correctness
+
+### 5. Demand Elegance (Balanced)
+
+- For non-trivial changes: pause and ask "is there a more elegant way?"
+- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
+- Skip this for simple, obvious fixes — don't over-engineer
+- Challenge your own work before presenting it
+
+### 6. Autonomous Bug Fixing
+
+- When given a bug report: just fix it. Don't ask for hand-holding.
+- Point at logs, errors, failing tests — then resolve them
+- Zero context switching required from the user
+- Go fix failing CI tests without being told how
+
+## Task Management
+
+1. **Plan First**: Create tasks via `task_create` with a `session_id` for the project/feature
+2. **Verify Plan**: Check in before starting implementation
+3. **Track Progress**: Update status via `task_update` (pending → in_progress → completed)
+4. **Explain Changes**: High-level summary at each step
+5. **Document Results**: Store session outcome as an `event` memory via `memory_add`
+6. **Capture Lessons**: Store corrections as `lesson` memories via `memory_add` — not local files
+
+At session start: `task_list(session_id="<project>", status="pending")` to resume open work.
+
+## Database Changes
+
+When schema changes are needed:
+1. Update `db/prisma/schema.prisma`
+2. Run `pnpm db:migrate:new <migration_name>` — generates SQL via `prisma migrate diff` and applies it
+3. Never run `prisma migrate dev` directly — it cannot handle the sqlite-vec virtual table
+
+## Core Principles
+
+- **Simplicity First**: Make every change as simple as possible. Impact minimal code.
+- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
+- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs.

package/dist/embeddings.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Gemini Embedding Module
+ * Generates vector embeddings for memory content using gemini-embedding-001
+ * Used by sqlite-vec for semantic similarity search (L2 retrieval)
+ */
+import 'dotenv/config';
+export declare const EMBEDDING_DIMENSIONS = 768;
+/**
+ * Generate an embedding vector for a text string.
+ * Returns a Float32Array suitable for sqlite-vec storage.
+ */
+export declare function embed(text: string): Promise<Float32Array>;
+/**
+ * Generate embeddings for multiple texts in one call.
+ * More efficient than calling embed() in a loop.
+ */
+export declare function embedBatch(texts: string[]): Promise<Float32Array[]>;

package/dist/embeddings.js

@@ -0,0 +1,46 @@
+/**
+ * Gemini Embedding Module
+ * Generates vector embeddings for memory content using gemini-embedding-001
+ * Used by sqlite-vec for semantic similarity search (L2 retrieval)
+ */
+import 'dotenv/config';
+import { GoogleGenAI } from '@google/genai';
+export const EMBEDDING_DIMENSIONS = 768;
+const EMBEDDING_MODEL = 'gemini-embedding-001';
+function getClient() {
+    const key = process.env.GEMINI_API_KEY;
+    if (!key)
+        throw new Error('GEMINI_API_KEY environment variable is required');
+    return new GoogleGenAI({ apiKey: key });
+}
+/**
+ * Generate an embedding vector for a text string.
+ * Returns a Float32Array suitable for sqlite-vec storage.
+ */
+export async function embed(text) {
+    const ai = getClient();
+    const response = await ai.models.embedContent({
+        model: EMBEDDING_MODEL,
+        contents: text,
+        config: {
+            outputDimensionality: EMBEDDING_DIMENSIONS,
+            taskType: 'SEMANTIC_SIMILARITY',
+        },
+    });
+    const values = response.embeddings?.[0]?.values;
+    if (!values || values.length !== EMBEDDING_DIMENSIONS) {
+        throw new Error(`Unexpected embedding response: got ${values?.length ?? 0} dimensions, expected ${EMBEDDING_DIMENSIONS}`);
+    }
+    return new Float32Array(values);
+}
+/**
+ * Generate embeddings for multiple texts in one call.
+ * More efficient than calling embed() in a loop.
+ */
+export async function embedBatch(texts) {
+    const results = [];
+    for (const text of texts) {
+        results.push(await embed(text));
+    }
+    return results;
+}

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Database connection and helpers using better-sqlite3 + sqlite-vec
+ * No ORM, just raw SQL - fast and simple
+ */
+import 'dotenv/config';
+import Database, { type Statement } from 'better-sqlite3';
+export declare function getDb(readonly?: boolean): Database.Database;
+export declare function closeDb(): void;
+export interface Memory {
+    id: number;
+    timestamp: string;
+    content: string;
+    content_l1: string | null;
+    type: string;
+    importance: number;
+    context: string | null;
+    supersedes_id: number | null;
+    last_accessed: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface MemoryWithTags extends Memory {
+    tags: string | null;
+}
+export interface MemoryWithScore extends MemoryWithTags {
+    effective_importance: number;
+}
+export interface VectorSearchResult extends MemoryWithTags {
+    distance: number;
+}
+export interface Tag {
+    id: number;
+    memory_id: number;
+    tag: string;
+}
+export interface Relationship {
+    id: number;
+    from_id: number;
+    to_id: number;
+    type: string;
+}
+export interface Preference {
+    id: number;
+    key: string;
+    value: string;
+    notes: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Journal {
+    id: number;
+    date: string;
+    content: string;
+    learned: string | null;
+    key_moments: string | null;
+    mood: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Task {
+    id: number;
+    title: string;
+    description: string | null;
+    status: string;
+    session_id: string | null;
+    memory_id: number | null;
+    created_at: string;
+    updated_at: string;
+}
+type QueryFactory = (db: Database.Database) => Statement;
+export declare const queries: Record<string, QueryFactory>;
+/**
+ * Touch last_accessed and log access in one transaction
+ */
+export declare function recordAccess(db: Database.Database, memoryId: number, context?: string): void;
+/**
+ * Create a memory with embedding and optional supersede
+ */
+export declare function createMemory(db: Database.Database, memory: {
+    timestamp: string;
+    content: string;
+    content_l1: string;
+    type: string;
+    core: number;
+    importance: number;
+    context?: string;
+    supersedes_id?: number;
+    tags: string[];
+    embedding: Float32Array;
+}): number;
+export declare function transaction<T>(db: Database.Database, fn: (db: Database.Database) => T): T;
+export {};

package/dist/index.js

@@ -0,0 +1,305 @@
+/**
+ * Database connection and helpers using better-sqlite3 + sqlite-vec
+ * No ORM, just raw SQL - fast and simple
+ */
+import 'dotenv/config';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Database from 'better-sqlite3';
+import * as sqliteVec from 'sqlite-vec';
+import { EMBEDDING_DIMENSIONS } from './embeddings.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DB_PATH = join(__dirname, '../memory.db');
+// Singleton connection
+let dbInstance = null;
+export function getDb(readonly = false) {
+    if (!dbInstance) {
+        dbInstance = new Database(DB_PATH, { readonly, fileMustExist: false });
+        // Load sqlite-vec extension
+        sqliteVec.load(dbInstance);
+        // Performance optimizations
+        dbInstance.pragma('journal_mode = WAL');
+        dbInstance.pragma('synchronous = NORMAL');
+        dbInstance.pragma('cache_size = -64000'); // 64MB cache
+        dbInstance.pragma('foreign_keys = ON');
+        // vec_memories virtual table — must live here because Prisma's shadow
+        // database doesn't load sqlite-vec, so migrations with vec0 will fail.
+        dbInstance.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS vec_memories USING vec0(
+        memory_id INTEGER PRIMARY KEY,
+        embedding float[${EMBEDDING_DIMENSIONS}]
+      );
+    `);
+    }
+    return dbInstance;
+}
+export function closeDb() {
+    if (dbInstance) {
+        dbInstance.close();
+        dbInstance = null;
+    }
+}
+export const queries = {
+    // Insert a new memory
+    insertMemory: (db) => db.prepare(`
+      INSERT INTO memory (timestamp, content, content_l1, type, core, importance, context, supersedes_id, last_accessed, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'), datetime('now'))
+    `),
+    // Insert a tag
+    insertTag: (db) => db.prepare('INSERT INTO tag (memory_id, tag) VALUES (?, ?)'),
+    // Insert a preference
+    insertPreference: (db) => db.prepare(`INSERT INTO preference (key, value, notes, created_at, updated_at)
+                VALUES (?, ?, ?, datetime('now'), datetime('now'))`),
+    // Insert embedding into vec_memories
+    insertEmbedding: (db) => db.prepare(`
+      INSERT INTO vec_memories (memory_id, embedding)
+      VALUES (?, ?)
+    `),
+    // -------------------------------------------------------------------
+    // L1: Working Memory with last-relevant decay
+    // -------------------------------------------------------------------
+    // Core memories first (no decay, always loaded), then regular memories fill remaining slots
+    getL1Summaries: (db) => db.prepare(`
+      SELECT
+        id, content_l1, type, importance, core, timestamp, last_accessed,
+        CASE
+          WHEN core = 1 THEN 100
+          ELSE importance
+            - CASE
+                WHEN julianday('now') - julianday(last_accessed) > 30 THEN 2
+                WHEN julianday('now') - julianday(last_accessed) > 14 THEN 1
+                ELSE 0
+              END
+        END AS effective_importance
+      FROM memory
+      WHERE content_l1 IS NOT NULL
+        AND (core = 1 OR importance >= 3)
+        AND id NOT IN (SELECT DISTINCT supersedes_id FROM memory WHERE supersedes_id IS NOT NULL)
+      ORDER BY effective_importance DESC, last_accessed DESC
+      LIMIT 50
+    `),
+    // -------------------------------------------------------------------
+    // L2: Vector similarity search
+    // -------------------------------------------------------------------
+    vectorSearch: (db) => db.prepare(`
+      SELECT
+        m.*,
+        v.distance,
+        GROUP_CONCAT(t.tag) AS tags
+      FROM vec_memories v
+      INNER JOIN memory m ON m.id = v.memory_id
+      LEFT JOIN tag t ON m.id = t.memory_id
+      WHERE v.embedding MATCH ?
+        AND k = ?
+      GROUP BY m.id
+      ORDER BY v.distance
+    `),
+    // Vector search filtered by type
+    vectorSearchByType: (db) => db.prepare(`
+      SELECT
+        m.*,
+        v.distance,
+        GROUP_CONCAT(t.tag) AS tags
+      FROM vec_memories v
+      INNER JOIN memory m ON m.id = v.memory_id
+      LEFT JOIN tag t ON m.id = t.memory_id
+      WHERE v.embedding MATCH ?
+        AND k = ?
+        AND m.type = ?
+      GROUP BY m.id
+      ORDER BY v.distance
+    `),
+    // -------------------------------------------------------------------
+    // Keyword search fallback
+    // -------------------------------------------------------------------
+    searchMemories: (db) => db.prepare(`
+      SELECT m.*, GROUP_CONCAT(t.tag) AS tags
+      FROM memory m
+      LEFT JOIN tag t ON m.id = t.memory_id
+      WHERE m.content LIKE ? OR m.content_l1 LIKE ?
+      GROUP BY m.id
+      ORDER BY m.importance DESC, m.timestamp DESC
+      LIMIT ?
+    `),
+    // -------------------------------------------------------------------
+    // Supersede
+    // -------------------------------------------------------------------
+    supersede: (db) => db.prepare(`
+      UPDATE memory
+      SET importance = MAX(1, importance - 2),
+          updated_at = datetime('now')
+      WHERE id = ?
+    `),
+    // Find supersede candidates — core memories are excluded (update content instead)
+    findSupersedeCandidates: (db) => db.prepare(`
+      SELECT m.id, m.content_l1, m.type, m.importance, m.core,
+             GROUP_CONCAT(t.tag) AS tags
+      FROM memory m
+      LEFT JOIN tag t ON m.id = t.memory_id
+      WHERE m.type = ?
+        AND m.importance >= 4
+        AND m.core = 0
+        AND m.id NOT IN (SELECT DISTINCT supersedes_id FROM memory WHERE supersedes_id IS NOT NULL)
+      GROUP BY m.id
+      ORDER BY m.timestamp DESC
+      LIMIT 20
+    `),
+    // Update a core memory's content in place (core memories cannot be superseded)
+    updateCoreMemory: (db) => db.prepare(`
+      UPDATE memory
+      SET content = ?, content_l1 = ?, updated_at = datetime('now')
+      WHERE id = ? AND core = 1
+    `),
+    // -------------------------------------------------------------------
+    // Access tracking
+    // -------------------------------------------------------------------
+    touchLastAccessed: (db) => db.prepare(`
+      UPDATE memory
+      SET last_accessed = datetime('now')
+      WHERE id = ?
+    `),
+    logAccess: (db) => db.prepare('INSERT INTO access_log (memory_id, context) VALUES (?, ?)'),
+    // -------------------------------------------------------------------
+    // Common queries
+    // -------------------------------------------------------------------
+    getRecentMemories: (db) => db.prepare(`
+      SELECT m.*, GROUP_CONCAT(t.tag) AS tags
+      FROM memory m
+      LEFT JOIN tag t ON m.id = t.memory_id
+      WHERE m.timestamp > datetime('now', ?)
+      GROUP BY m.id
+      ORDER BY m.timestamp DESC
+      LIMIT ?
+    `),
+    getMemoriesByContext: (db) => db.prepare(`
+      SELECT m.*, GROUP_CONCAT(t.tag) AS tags
+      FROM memory m
+      LEFT JOIN tag t ON m.id = t.memory_id
+      WHERE m.context LIKE ?
+      GROUP BY m.id
+      ORDER BY m.importance DESC, m.timestamp DESC
+      LIMIT ?
+    `),
+    getMemoriesByTag: (db) => db.prepare(`
+      SELECT m.*, GROUP_CONCAT(t.tag) AS tags
+      FROM memory m
+      INNER JOIN tag t ON m.id = t.memory_id
+      WHERE t.tag = ?
+      GROUP BY m.id
+      ORDER BY m.importance DESC, m.timestamp DESC
+      LIMIT ?
+    `),
+    getStats: (db) => db.prepare(`
+      SELECT
+        type,
+        COUNT(*) AS count,
+        AVG(importance) AS avg_importance
+      FROM memory
+      GROUP BY type
+    `),
+    // Walk a supersede chain backwards from a memory
+    getSupersedeChain: (db) => db.prepare(`
+      WITH RECURSIVE chain(id, content_l1, type, importance, supersedes_id, depth) AS (
+        SELECT id, content_l1, type, importance, supersedes_id, 0
+        FROM memory WHERE id = ?
+        UNION ALL
+        SELECT m.id, m.content_l1, m.type, m.importance, m.supersedes_id, c.depth + 1
+        FROM memory m
+        INNER JOIN chain c ON m.id = c.supersedes_id
+        WHERE c.depth < 10
+      )
+      SELECT * FROM chain ORDER BY depth
+    `),
+    // -------------------------------------------------------------------
+    // Journal
+    // -------------------------------------------------------------------
+    insertJournal: (db) => db.prepare(`
+      INSERT INTO journal (date, content, learned, key_moments, mood, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+      ON CONFLICT(date) DO UPDATE SET
+        content     = excluded.content,
+        learned     = excluded.learned,
+        key_moments = excluded.key_moments,
+        mood        = excluded.mood,
+        updated_at  = datetime('now')
+    `),
+    getRecentJournals: (db) => db.prepare(`
+      SELECT *
+      FROM journal
+      WHERE date >= date('now', ?)
+      ORDER BY date DESC
+    `),
+    // -------------------------------------------------------------------
+    // Relationships with memory context
+    // -------------------------------------------------------------------
+    getMemoryRelationships: (db) => db.prepare(`
+      SELECT
+        r.id, r.type,
+        r.from_id, f.content_l1 AS from_content_l1,
+        r.to_id,   t.content_l1 AS to_content_l1
+      FROM relationship r
+      JOIN memory f ON f.id = r.from_id
+      JOIN memory t ON t.id = r.to_id
+      WHERE r.from_id = ? OR r.to_id = ?
+    `),
+    // -------------------------------------------------------------------
+    // Tasks
+    // -------------------------------------------------------------------
+    insertTask: (db) => db.prepare(`
+      INSERT INTO task (title, description, status, session_id, memory_id, created_at, updated_at)
+      VALUES (?, ?, 'pending', ?, ?, datetime('now'), datetime('now'))
+    `),
+    updateTask: (db) => db.prepare(`
+      UPDATE task
+      SET
+        status      = COALESCE(?, status),
+        title       = COALESCE(?, title),
+        description = COALESCE(?, description),
+        updated_at  = datetime('now')
+      WHERE id = ?
+    `),
+    getTaskById: (db) => db.prepare(`SELECT * FROM task WHERE id = ?`),
+};
+// -------------------------------------------------------------------
+// Helper functions
+// -------------------------------------------------------------------
+/**
+ * Touch last_accessed and log access in one transaction
+ */
+export function recordAccess(db, memoryId, context) {
+    const txn = db.transaction(() => {
+        queries.touchLastAccessed(db).run(memoryId);
+        queries.logAccess(db).run(memoryId, context || null);
+    });
+    txn();
+}
+/**
+ * Create a memory with embedding and optional supersede
+ */
+export function createMemory(db, memory) {
+    let memoryId = 0;
+    const txn = db.transaction(() => {
+        // Insert memory
+        const result = queries.insertMemory(db).run(memory.timestamp, memory.content, memory.content_l1, memory.type, memory.core, memory.importance, memory.context || null, memory.supersedes_id || null);
+        memoryId = Number(result.lastInsertRowid);
+        // Insert tags
+        const insertTag = queries.insertTag(db);
+        for (const tag of memory.tags) {
+            insertTag.run(memoryId, tag);
+        }
+        // Insert embedding into vec0 virtual table
+        // vec0 requires bigint for PK, better-sqlite3 requires Buffer for blobs
+        queries.insertEmbedding(db).run(BigInt(memoryId), Buffer.from(memory.embedding.buffer));
+        // If superseding, demote the old memory
+        if (memory.supersedes_id && memory.core < 1) {
+            queries.supersede(db).run(memory.supersedes_id);
+        }
+    });
+    txn();
+    return memoryId;
+}
+// Transaction helper
+export function transaction(db, fn) {
+    const txn = db.transaction(fn);
+    return txn(db);
+}

package/dist/migrate-diff.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Generate + apply a new migration from schema.prisma changes.
+ *
+ * Uses `prisma migrate diff` to produce SQL (no DB introspection needed),
+ * writes it to a timestamped migrations directory, then applies it via
+ * the same runner used by `db:migrate`.
+ *
+ * Usage:
+ *   tsx src/migrate-diff.ts <migration_name>
+ *
+ * Example:
+ *   tsx src/migrate-diff.ts add_user_table
+ */
+export {};

package/dist/migrate-diff.js

@@ -0,0 +1,62 @@
+/**
+ * Generate + apply a new migration from schema.prisma changes.
+ *
+ * Uses `prisma migrate diff` to produce SQL (no DB introspection needed),
+ * writes it to a timestamped migrations directory, then applies it via
+ * the same runner used by `db:migrate`.
+ *
+ * Usage:
+ *   tsx src/migrate-diff.ts <migration_name>
+ *
+ * Example:
+ *   tsx src/migrate-diff.ts add_user_table
+ */
+import { execSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdirSync, writeFileSync } from 'node:fs';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MIGRATIONS_DIR = join(__dirname, '../prisma/migrations');
+const name = process.argv[2];
+if (!name) {
+    console.error('Usage: tsx src/migrate-diff.ts <migration_name>');
+    console.error('Example: tsx src/migrate-diff.ts add_user_table');
+    process.exit(1);
+}
+// Timestamp: YYYYMMDDHHmmss
+const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
+const migrationName = `${ts}_${name}`;
+const migrationDir = join(MIGRATIONS_DIR, migrationName);
+// Generate SQL via prisma migrate diff (no DB connection required)
+// --from-migrations = current applied state (from the SQL files)
+// --to-schema-datamodel = desired state (schema.prisma)
+let sql;
+try {
+    sql = execSync(`pnpm prisma migrate diff \
+      --from-migrations ./prisma/migrations \
+      --to-schema ./prisma/schema.prisma \
+      --script`, { cwd: join(__dirname, '..'), encoding: 'utf8' });
+}
+catch (err) {
+    console.error('prisma migrate diff failed:\n', err.stderr ?? err.message);
+    process.exit(1);
+}
+if (!sql.trim() || sql.trim() === '-- This is an empty migration.') {
+    console.log('No schema changes detected — nothing to generate.');
+    process.exit(0);
+}
+// Write migration file
+mkdirSync(migrationDir, { recursive: true });
+writeFileSync(join(migrationDir, 'migration.sql'), sql);
+console.log(`Generated: prisma/migrations/${migrationName}/migration.sql`);
+// Apply immediately via the migrate runner
+const { execFileSync } = await import('node:child_process');
+try {
+    execFileSync('pnpm', ['db:migrate'], {
+        cwd: join(__dirname, '..'),
+        stdio: 'inherit',
+    });
+}
+catch {
+    process.exit(1);
+}

package/dist/migrate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Custom migration runner for better-sqlite3 + sqlite-vec.
+ *
+ * Prisma's migration engine doesn't load sqlite-vec, so `prisma migrate dev`
+ * fails when the vec_memories virtual table is present. This script replaces
+ * it: opens the DB the same way getDb() does (with sqlite-vec loaded), reads
+ * pending SQL files from prisma/migrations/, applies them, and records each
+ * in _prisma_migrations so Prisma's history stays consistent.
+ *
+ * Usage:
+ *   tsx src/migrate.ts          — apply all pending migrations
+ *   tsx src/migrate.ts --status — list applied / pending migrations
+ */
+export {};

package/dist/migrate.js

@@ -0,0 +1,121 @@
+/**
+ * Custom migration runner for better-sqlite3 + sqlite-vec.
+ *
+ * Prisma's migration engine doesn't load sqlite-vec, so `prisma migrate dev`
+ * fails when the vec_memories virtual table is present. This script replaces
+ * it: opens the DB the same way getDb() does (with sqlite-vec loaded), reads
+ * pending SQL files from prisma/migrations/, applies them, and records each
+ * in _prisma_migrations so Prisma's history stays consistent.
+ *
+ * Usage:
+ *   tsx src/migrate.ts          — apply all pending migrations
+ *   tsx src/migrate.ts --status — list applied / pending migrations
+ */
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import Database from 'better-sqlite3';
+import * as sqliteVec from 'sqlite-vec';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DB_PATH = join(__dirname, '../memory.db');
+const MIGRATIONS_DIR = join(__dirname, '../prisma/migrations');
+// -------------------------------------------------------------------
+// Open DB with sqlite-vec loaded (mirrors getDb() setup)
+// -------------------------------------------------------------------
+const db = new Database(DB_PATH, { fileMustExist: false });
+sqliteVec.load(db);
+db.pragma('journal_mode = WAL');
+db.pragma('foreign_keys = ON');
+// Ensure _prisma_migrations table exists (Prisma creates this on first migrate)
+db.exec(`
+  CREATE TABLE IF NOT EXISTS _prisma_migrations (
+    id                  TEXT PRIMARY KEY,
+    checksum            TEXT NOT NULL,
+    finished_at         DATETIME,
+    migration_name      TEXT NOT NULL,
+    logs                TEXT,
+    rolled_back_at      DATETIME,
+    started_at          DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    applied_steps_count INTEGER NOT NULL DEFAULT 0
+  )
+`);
+// -------------------------------------------------------------------
+// Read migration directories (sorted = chronological)
+// -------------------------------------------------------------------
+function getMigrationDirs() {
+    if (!existsSync(MIGRATIONS_DIR))
+        return [];
+    return readdirSync(MIGRATIONS_DIR, { withFileTypes: true })
+        .filter(d => d.isDirectory() && d.name !== 'migration_lock.toml')
+        .map(d => d.name)
+        .sort();
+}
+function getApplied() {
+    const rows = db.prepare('SELECT migration_name FROM _prisma_migrations WHERE rolled_back_at IS NULL AND finished_at IS NOT NULL').all();
+    return new Set(rows.map(r => r.migration_name));
+}
+// -------------------------------------------------------------------
+// Status
+// -------------------------------------------------------------------
+function status() {
+    const all = getMigrationDirs();
+    const applied = getApplied();
+    console.log('\nMigration status:\n');
+    for (const name of all) {
+        const state = applied.has(name) ? '✓ applied ' : '○ pending ';
+        console.log(`  ${state}  ${name}`);
+    }
+    const pending = all.filter(n => !applied.has(n));
+    console.log(`\n${applied.size} applied, ${pending.length} pending\n`);
+}
+// -------------------------------------------------------------------
+// Apply pending migrations
+// -------------------------------------------------------------------
+function migrate() {
+    const all = getMigrationDirs();
+    const applied = getApplied();
+    const pending = all.filter(n => !applied.has(n));
+    if (pending.length === 0) {
+        console.log('Nothing to migrate — all migrations are already applied.');
+        return;
+    }
+    console.log(`Applying ${pending.length} migration(s)...\n`);
+    for (const name of pending) {
+        const sqlPath = join(MIGRATIONS_DIR, name, 'migration.sql');
+        if (!existsSync(sqlPath)) {
+            console.warn(`  ⚠ Skipping ${name} — no migration.sql found`);
+            continue;
+        }
+        const sql = readFileSync(sqlPath, 'utf8');
+        const id = randomUUID();
+        const startedAt = new Date().toISOString();
+        try {
+            db.transaction(() => {
+                db.exec(sql);
+                db.prepare(`
+          INSERT INTO _prisma_migrations
+            (id, checksum, finished_at, migration_name, logs, rolled_back_at, started_at, applied_steps_count)
+          VALUES
+            (?, '', datetime('now'), ?, NULL, NULL, ?, 1)
+        `).run(id, name, startedAt);
+            })();
+            console.log(`  ✓ ${name}`);
+        }
+        catch (err) {
+            console.error(`  ✗ ${name}\n    ${err.message}`);
+            process.exit(1);
+        }
+    }
+    console.log('\nDone.');
+}
+// -------------------------------------------------------------------
+// Entry point
+// -------------------------------------------------------------------
+const args = process.argv.slice(2);
+if (args.includes('--status')) {
+    status();
+}
+else {
+    migrate();
+}

package/dist/seed.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Seed the core operational memory — the guide that teaches the model
+ * how to use the memory system. This is the highest-priority memory
+ * and should never decay out of L1.
+ */
+export {};

package/dist/seed.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Seed the core operational memory — the guide that teaches the model
+ * how to use the memory system. This is the highest-priority memory
+ * and should never decay out of L1.
+ */
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getDb, createMemory, closeDb } from './index.js';
+import { embed } from './embeddings.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+async function bootstrap(file, name, tags, content_l1) {
+    const mdPath = join(__dirname, '../core', file);
+    const content = readFileSync(mdPath, 'utf-8');
+    console.log('Generating embedding...');
+    const embedding = await embed(content);
+    console.log('Inserting core memory...');
+    const db = getDb(false);
+    const memoryId = createMemory(db, {
+        timestamp: new Date().toISOString(),
+        content,
+        content_l1: content_l1.join(),
+        type: 'decision',
+        importance: 5,
+        core: 1,
+        context: name,
+        tags: tags.concat([
+            'core-memory',
+            'always-load'
+        ]),
+        embedding,
+    });
+    console.log(`Created core memory #${memoryId}`);
+    console.log(`  Type: decision`);
+    console.log(`  Importance: 5`);
+    console.log(`  Embedding: ${embedding.length} dimensions`);
+    console.log(`  Content: ${content.length} chars`);
+    console.log(`  L1 summary: ${content_l1.length} chars`);
+}
+try {
+    await bootstrap('./BOOTSTRAP.md', 'memory-system-bootstrap', [
+        'operational-guide',
+        'memory-system',
+        'bootstrap'
+    ], [
+        'CORE: Memory system operational guide.',
+        'L1=auto-loaded working memory, L2=vector search, L3=deep storage.',
+        'Tools: memory_search, memory_add, memory_update_core, memory_recent, memory_stats, memory_consolidate, journal_add, journal_recent, task_create, task_update, task_list.',
+        'SESSION START: task_list(status=pending) to resume work + memory_search("lesson").',
+        'TASKS: task_create(title,session_id)→in_progress→completed. Tasks persist across sessions.',
+        'Core memories: update with memory_update_core, never supersede.',
+        'Create memories: decisions(5), preferences(5), person(5), lessons(3-5), technical(3-4), events(1-4).',
+        'Supersede regular memories via supersedes_id. Rules: search first, store decisions now, tasks over files.',
+    ]);
+    await bootstrap('WORKFLOW.md', 'workflow-principles', [
+        'workflow',
+        'principles'
+    ], [
+        'CORE: Workflow rules.',
+        'Plan mode for any 3+ step task; re-plan on derailment.',
+        'Subagents for research/parallel work.',
+        'Self-improve: store lesson memories via memory_add(type:lesson) after every correction.',
+        'Search memory_search("lesson") at session start. Verify before done: prove it works.',
+        'Bug reports: just fix autonomously.',
+        'Task flow: task_create(session_id)→task_update(in_progress)→task_update(completed).',
+        'Session start: task_list(session_id, status=pending) to resume open work.',
+        'Results→event memory. Lessons→lesson memory.',
+        'Principles: simplicity first, no laziness, minimal impact.'
+    ]);
+    closeDb();
+    console.log('\nDone.');
+}
+catch (err) {
+    console.error('Failed:', err);
+    process.exit(1);
+}
+;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@postnesia/db",
+  "version": "0.1.0",
+  "description": "AI Agent memory context database",
+  "type": "module",
+  "private": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "postnesia-seed": "./dist/seed.js"
+  },
+  "files": [
+    "dist",
+    "core",
+    "prisma/schema.prisma"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./embeddings": {
+      "types": "./dist/embeddings.d.ts",
+      "import": "./dist/embeddings.js"
+    }
+  },
+  "dependencies": {
+    "@google/genai": "^1.42.0",
+    "@prisma/adapter-better-sqlite3": "^7.4.0",
+    "better-sqlite3": "11.10.0",
+    "dotenv": "^17.3.1",
+    "sqlite-vec": "^0.1.7-alpha.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.10.5",
+    "prisma": "^7.4.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "db:generate": "prisma generate",
+    "db:migrate": "tsx src/migrate.ts",
+    "db:migrate:status": "tsx src/migrate.ts --status",
+    "db:migrate:diff": "tsx src/migrate-diff.ts",
+    "backup": "tsx src/backup.ts",
+    "seed": "tsx src/seed.ts"
+  }
+}

package/prisma/schema.prisma

@@ -0,0 +1,126 @@
+// Belle's Memory Schema - Prisma v7
+// Using Prisma for migrations only, not ORM
+// Queries use raw better-sqlite3 for performance
+
+datasource db {
+  provider = "sqlite"
+}
+
+// Core memory storage
+model memory {
+  id            Int      @id @default(autoincrement())
+  timestamp     DateTime @default(now())
+  content       String
+  content_l1    String?
+  type          String
+  importance    Int      @default(3)
+  context       String?
+  supersedes_id Int?
+  last_accessed DateTime @default(now())
+  core          Boolean  @default(false) // If this is a core memory it should not be deleted by when it is contradicted it should be updated to reflect the new information.
+
+  created_at DateTime @default(now())
+  updated_at DateTime @updatedAt
+
+  // Self-referential: this memory supersedes another
+  supersedes    memory?  @relation("supersede_chain", fields: [supersedes_id], references: [id])
+  superseded_by memory[] @relation("supersede_chain")
+
+  tags         tag[]
+  related_from relationship[] @relation("from_memory")
+  related_to   relationship[] @relation("to_memory")
+  access       access_log[]
+  tasks        task[]
+
+  @@index([timestamp])
+  @@index([type])
+  @@index([importance])
+  @@index([last_accessed])
+  @@index([supersedes_id])
+  @@index([type, importance])
+}
+
+// Flexible tagging system
+model tag {
+  id        Int    @id @default(autoincrement())
+  memory_id Int
+  tag       String
+
+  memory memory @relation(fields: [memory_id], references: [id], onDelete: Cascade)
+
+  @@index([tag])
+  @@index([memory_id])
+}
+
+// How memories connect to each other
+model relationship {
+  id      Int    @id @default(autoincrement())
+  from_id Int
+  to_id   Int
+  type    String
+
+  from memory @relation("from_memory", fields: [from_id], references: [id], onDelete: Cascade)
+  to   memory @relation("to_memory", fields: [to_id], references: [id], onDelete: Cascade)
+
+  @@index([from_id])
+  @@index([to_id])
+}
+
+// Track memory access patterns (for relevance scoring)
+model access_log {
+  id          Int      @id @default(autoincrement())
+  memory_id   Int
+  accessed_at DateTime @default(now())
+  context     String?
+
+  memory memory @relation(fields: [memory_id], references: [id], onDelete: Cascade)
+
+  @@index([memory_id])
+  @@index([accessed_at])
+}
+
+// Preferences shorthand - quick lookup for common patterns
+model preference {
+  id    Int     @id @default(autoincrement())
+  key   String  @unique
+  value String
+  notes String?
+
+  created_at DateTime @default(now())
+  updated_at DateTime @updatedAt
+
+  @@index([key])
+}
+
+// Persistent task tracking — survives across sessions
+model task {
+  id          Int     @id @default(autoincrement())
+  title       String
+  description String?
+  status      String  @default("pending") // pending | in_progress | completed | cancelled
+  session_id  String? // free-form label: project name, feature branch, date, etc.
+  memory_id   Int?    // optional link to a related memory
+
+  created_at DateTime @default(now())
+  updated_at DateTime @updatedAt
+
+  memory memory? @relation(fields: [memory_id], references: [id], onDelete: SetNull)
+
+  @@index([status])
+  @@index([session_id])
+}
+
+// Daily journal entries - narrative reflections
+model journal {
+  id          Int     @id @default(autoincrement())
+  date        String  @unique
+  content     String
+  learned     String?
+  key_moments String?
+  mood        String?
+
+  created_at DateTime @default(now())
+  updated_at DateTime @updatedAt
+
+  @@index([date])
+}