smaran 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajaybabu Putti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# smaran
+
+**Professional memory for AI agents — with an undo button.**
+
+*Smaran* (स्मरण) is Sanskrit for remembrance — not just storing something, but the act of holding it with care.
+
+Every memory tool promises your agent will remember. The real problem is what agents *write*: guesses saved as facts, duplicates, stale state — then recalled with perfect confidence forever. smaran is a local MCP memory server built around the write path:
+
+- **Typed writes** — agents can't dump arbitrary text; a memory is a *decision*, a *preference*, a *task*, an *event*, with structure
+- **Refuse by default** — writes against unknown projects/people are rejected; creation is explicit and audited
+- **Append-only audit log** — every write records before/after state and which app made it
+- **Undo** — `revert_write` reverses any write; the history of the revert is itself kept
+- **Supersede, don't delete** — when a fact changes, the old one is replaced, never silently lost
+
+Local-first: one SQLite file on your machine (`~/.smaran/memory.db`). No Docker, no API keys, no account, no open ports, no telemetry.
+
+## Install (under 5 minutes)
+
+**Claude Code**
+
+```bash
+claude mcp add memory -- npx -y smaran
+```
+
+**Claude Desktop / Cursor / Windsurf** — add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "memory": { "command": "npx", "args": ["-y", "smaran"] }
+  }
+}
+```
+
+That's it. Ask your agent to *"create a project for X and remember that we decided Y"*, then in a new session ask *"what do you know about project X?"*
+
+Custom database location: `npx smaran --db /path/to/memory.db` or set `SMARAN_DB`.
+
+## Tools
+
+| Read | Write | Audit |
+|---|---|---|
+| `search_memories` (BM25) | `create_project` | `list_recent_writes` |
+| `list_projects` / `list_people` / `list_companies` | `add_person` / `add_company` | `revert_write` |
+| `get_project_context` | `store_decision` | |
+| `get_person_context` | `log_event` | |
+| `get_company_context` | `update_project_state` | |
+| `get_recent_decisions` | `save_preference` | |
+| `get_open_loops` | `set_next_step` / `mark_done` | |
+| `prepare_task_brief` | `append_note` | |
+
+Entity tools accept ids **or names** (`get_project_context("atlas")`), because that's how models actually call them.
+
+## Why keyword search instead of embeddings?
+
+The caller is an LLM. If a search misses, it retries with synonyms or browses with the context tools — the semantic understanding lives in the model, not the index. At personal scale (thousands of memories, not millions), BM25 over *typed* content retrieves what matters, with zero API keys and zero setup. Typed entities are the source of truth; the search index is regenerated from them and safe to rebuild.
+
+## The agent contract
+
+Add this to your agent instructions (CLAUDE.md, Cursor rules, custom instructions):
+
+> Before starting work, call `prepare_task_brief` or `get_project_context` to load relevant context.
+> After finishing, store only durable outcomes: decisions made, status changes, preferences learned, promises, blockers, next steps. Use the most specific tool available. Never store speculation, drafts, or chain-of-thought.
+> When a stored fact is no longer true, supersede it — don't ignore it.
+
+## Recovering from bad writes
+
+```
+you : what did you save to memory this session?
+agent: [calls list_recent_writes] I stored 3 things: …
+you : the second one is wrong, undo it
+agent: [calls revert_write] Done — reverted, and the revert is logged.
+```
+
+The audit log is append-only. Reverts never erase history; they add to it.
+
+## Roadmap
+
+- Hosted sync (same typed schema, cloud endpoint for browser ChatGPT/Claude/Gemini and cross-device memory)
+- Smart reconciliation: fuzzy dedupe, conflict detection, memory-quality sweeps
+- Optional local embeddings for semantic search
+
+MIT licensed.

package/dist/db.js

@@ -0,0 +1,152 @@
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+// Same typed schema as the cloud product (infrastructure/init.sql), minus
+// users/tokens (single-user local) and memory_chunks/embeddings (FTS5 takes
+// the retrieval role here). Arrays become JSON TEXT columns.
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS companies (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  industry TEXT, stage TEXT, priority TEXT, notes TEXT,
+  source_type TEXT DEFAULT 'model', source_app TEXT, source_ref TEXT,
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS people (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  role TEXT,
+  company_id TEXT REFERENCES companies(id) ON DELETE SET NULL,
+  relationship_type TEXT,
+  communication_preferences TEXT,
+  important_context TEXT,
+  last_interaction_at TEXT,
+  source_type TEXT DEFAULT 'model', source_app TEXT, source_ref TEXT,
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS projects (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  description TEXT,
+  status TEXT DEFAULT 'active',
+  goals TEXT,        -- JSON array
+  constraints TEXT,  -- JSON array
+  owners TEXT,       -- JSON array
+  source_type TEXT DEFAULT 'model', source_app TEXT, source_ref TEXT,
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS decisions (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  decision TEXT NOT NULL,
+  rationale TEXT,
+  scope TEXT,
+  project_id TEXT REFERENCES projects(id) ON DELETE SET NULL,
+  decided_by TEXT,
+  decided_at TEXT,
+  superseded_by TEXT REFERENCES decisions(id) ON DELETE SET NULL,
+  confidence REAL DEFAULT 0.8,
+  source_type TEXT DEFAULT 'model', source_app TEXT, source_ref TEXT,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_decisions_created ON decisions(created_at DESC);
+
+CREATE TABLE IF NOT EXISTS preferences (
+  id TEXT PRIMARY KEY,
+  subject_type TEXT NOT NULL,   -- 'person' | 'company' | 'project' | 'self'
+  subject_id TEXT,
+  preference_type TEXT,
+  value TEXT NOT NULL,
+  strength REAL DEFAULT 0.8,
+  last_verified_at TEXT,
+  superseded_by TEXT REFERENCES preferences(id) ON DELETE SET NULL,
+  source_type TEXT DEFAULT 'model', source_app TEXT, source_ref TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS events (
+  id TEXT PRIMARY KEY,
+  title TEXT,
+  summary TEXT NOT NULL,
+  occurred_at TEXT,
+  project_id TEXT REFERENCES projects(id) ON DELETE SET NULL,
+  person_ids TEXT,   -- JSON array
+  company_ids TEXT,  -- JSON array
+  durability REAL DEFAULT 0.7,
+  source_type TEXT DEFAULT 'model', source_app TEXT, source_ref TEXT,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_events_occurred ON events(occurred_at DESC);
+
+CREATE TABLE IF NOT EXISTS tasks (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  status TEXT DEFAULT 'open',   -- open | in_progress | blocked | done | cancelled
+  owner TEXT,
+  due_at TEXT,
+  project_id TEXT REFERENCES projects(id) ON DELETE SET NULL,
+  blocked_by TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+  completed_at TEXT,
+  source_type TEXT DEFAULT 'model', source_app TEXT, source_ref TEXT,
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
+
+-- One row per project; '' = global working state.
+CREATE TABLE IF NOT EXISTS working_state (
+  project_id TEXT PRIMARY KEY DEFAULT '',
+  current_focus TEXT,
+  active_blockers TEXT,        -- JSON array
+  this_week_priorities TEXT,   -- JSON array
+  open_loops TEXT,             -- JSON array
+  last_updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS notes (
+  id TEXT PRIMARY KEY,
+  content TEXT NOT NULL,
+  project_id TEXT REFERENCES projects(id) ON DELETE SET NULL,
+  tags TEXT,  -- JSON array
+  source_type TEXT DEFAULT 'model', source_app TEXT, source_ref TEXT,
+  created_at TEXT NOT NULL
+);
+
+-- Append-only. Rows are never deleted; revert marks them and adds a new row.
+CREATE TABLE IF NOT EXISTS audit_log (
+  id TEXT PRIMARY KEY,
+  action TEXT NOT NULL,        -- 'create' | 'update' | 'supersede' | 'revert'
+  entity_kind TEXT NOT NULL,
+  entity_id TEXT NOT NULL,
+  before_state TEXT,           -- JSON
+  after_state TEXT,            -- JSON
+  source_type TEXT DEFAULT 'model',
+  source_app TEXT,
+  source_ref TEXT,
+  reverted INTEGER DEFAULT 0,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_audit_created ON audit_log(created_at DESC);
+
+-- Keyword retrieval layer (BM25). Typed rows are the source of truth; this
+-- index is regenerated from them and safe to rebuild.
+CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+  content, kind UNINDEXED, ref_id UNINDEXED, project_id UNINDEXED
+);
+`;
+export function defaultDbPath() {
+    return (process.env.SMARAN_DB ??
+        path.join(homedir(), '.smaran', 'memory.db'));
+}
+export function openDb(dbPath) {
+    const file = dbPath ?? defaultDbPath();
+    mkdirSync(path.dirname(file), { recursive: true });
+    const db = new Database(file);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    db.exec(SCHEMA);
+    return db;
+}

package/dist/index.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { openDb, defaultDbPath } from './db.js';
+import { Store } from './store.js';
+import { buildTools } from './tools.js';
+function parseDbArg() {
+    const i = process.argv.indexOf('--db');
+    if (i !== -1 && process.argv[i + 1])
+        return process.argv[i + 1];
+    return undefined;
+}
+const dbPath = parseDbArg() ?? defaultDbPath();
+const db = openDb(dbPath);
+const store = new Store(db);
+const tools = buildTools(store);
+const server = new Server({ name: 'smaran', version: '0.1.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = tools.find((t) => t.name === req.params.name);
+    if (!tool) {
+        return { content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }], isError: true };
+    }
+    const ctx = {
+        sourceType: 'model',
+        sourceApp: server.getClientVersion()?.name ?? 'mcp',
+        sourceRef: null,
+    };
+    try {
+        const result = await tool.handler(req.params.arguments ?? {}, ctx);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e?.message ?? e}` }], isError: true };
+    }
+});
+await server.connect(new StdioServerTransport());
+// stdout carries the protocol; human-facing output goes to stderr.
+console.error(`smaran MCP server ready · db: ${dbPath}`);

package/dist/store.js

@@ -0,0 +1,653 @@
+import { randomUUID } from 'node:crypto';
+const TABLE = {
+    project: 'projects',
+    person: 'people',
+    company: 'companies',
+    decision: 'decisions',
+    preference: 'preferences',
+    event: 'events',
+    task: 'tasks',
+    note: 'notes',
+};
+const now = () => new Date().toISOString();
+const toJson = (v) => (v == null ? null : JSON.stringify(v));
+const fromJson = (v) => (typeof v === 'string' ? JSON.parse(v) : v);
+function parseRow(row, jsonCols) {
+    if (!row)
+        return row;
+    const out = { ...row };
+    for (const c of jsonCols)
+        if (out[c] != null)
+            out[c] = fromJson(out[c]);
+    return out;
+}
+export class Store {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // ------------------------------------------------------------- audit + fts
+    audit(ctx, action, kind, entityId, before, after) {
+        const id = randomUUID();
+        this.db
+            .prepare(`INSERT INTO audit_log (id, action, entity_kind, entity_id, before_state, after_state,
+                                source_type, source_app, source_ref, reverted, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, ?)`)
+            .run(id, action, kind, entityId, toJson(before), toJson(after), ctx.sourceType, ctx.sourceApp, ctx.sourceRef, now());
+        return id;
+    }
+    ftsSet(kind, refId, content, projectId) {
+        this.db.prepare(`DELETE FROM memory_fts WHERE kind = ? AND ref_id = ?`).run(kind, refId);
+        this.db
+            .prepare(`INSERT INTO memory_fts (content, kind, ref_id, project_id) VALUES (?, ?, ?, ?)`)
+            .run(content, kind, refId, projectId);
+    }
+    ftsDelete(kind, refId) {
+        this.db.prepare(`DELETE FROM memory_fts WHERE kind = ? AND ref_id = ?`).run(kind, refId);
+    }
+    ftsContent(kind, row) {
+        switch (kind) {
+            case 'decision':
+                return [row.title, row.decision, row.rationale, row.scope].filter(Boolean).join('. ');
+            case 'event':
+                return [row.title, row.summary].filter(Boolean).join('. ');
+            case 'preference':
+                return [row.subject_type, row.preference_type, row.value].filter(Boolean).join(': ');
+            case 'project':
+                return [row.name, row.description, ...(fromJson(row.goals) ?? []), ...(fromJson(row.constraints) ?? [])]
+                    .filter(Boolean)
+                    .join('. ');
+            case 'person':
+                return [row.name, row.role, row.relationship_type, row.communication_preferences, row.important_context]
+                    .filter(Boolean)
+                    .join('. ');
+            case 'company':
+                return [row.name, row.industry, row.stage, row.notes].filter(Boolean).join('. ');
+            case 'task':
+                return [row.title, row.status, row.owner].filter(Boolean).join('. ');
+            case 'note':
+                return row.content;
+            default:
+                return '';
+        }
+    }
+    // ------------------------------------------------------------- resolution
+    // Accept either an id or an exact (case-insensitive) name. We deliberately
+    // do NOT auto-create on miss: writes against unknown entities are refused so
+    // the model must create them explicitly (and that creation is audited).
+    resolveProject(idOrName) {
+        if (!idOrName)
+            return null;
+        const byId = this.db.prepare(`SELECT * FROM projects WHERE id = ?`).get(idOrName);
+        if (byId)
+            return parseRow(byId, ['goals', 'constraints', 'owners']);
+        const byName = this.db
+            .prepare(`SELECT * FROM projects WHERE lower(name) = lower(?)`)
+            .get(idOrName);
+        if (byName)
+            return parseRow(byName, ['goals', 'constraints', 'owners']);
+        return null;
+    }
+    requireProjectId(idOrName) {
+        if (!idOrName)
+            return null;
+        const p = this.resolveProject(idOrName);
+        if (!p) {
+            throw new Error(`project "${idOrName}" not found — call list_projects to see existing projects or create_project to add it first`);
+        }
+        return p.id;
+    }
+    resolvePerson(idOrName) {
+        if (!idOrName)
+            return null;
+        return (this.db.prepare(`SELECT * FROM people WHERE id = ?`).get(idOrName) ??
+            this.db.prepare(`SELECT * FROM people WHERE lower(name) = lower(?)`).get(idOrName) ??
+            null);
+    }
+    resolveCompany(idOrName) {
+        if (!idOrName)
+            return null;
+        return (this.db.prepare(`SELECT * FROM companies WHERE id = ?`).get(idOrName) ??
+            this.db.prepare(`SELECT * FROM companies WHERE lower(name) = lower(?)`).get(idOrName) ??
+            null);
+    }
+    // ------------------------------------------------------------- entity writes
+    createProject(ctx, args) {
+        const existing = this.resolveProject(args.name);
+        if (existing)
+            throw new Error(`project "${args.name}" already exists (id ${existing.id})`);
+        const id = randomUUID();
+        const ts = now();
+        const row = {
+            id,
+            name: args.name,
+            description: args.description ?? null,
+            status: args.status ?? 'active',
+            goals: toJson(args.goals),
+            constraints: toJson(args.constraints),
+            owners: toJson(args.owners),
+            source_type: ctx.sourceType,
+            source_app: ctx.sourceApp,
+            source_ref: ctx.sourceRef,
+            created_at: ts,
+            updated_at: ts,
+        };
+        this.db
+            .prepare(`INSERT INTO projects (id, name, description, status, goals, constraints, owners,
+                               source_type, source_app, source_ref, created_at, updated_at)
+         VALUES (@id, @name, @description, @status, @goals, @constraints, @owners,
+                 @source_type, @source_app, @source_ref, @created_at, @updated_at)`)
+            .run(row);
+        this.ftsSet('project', id, this.ftsContent('project', row), id);
+        const auditId = this.audit(ctx, 'create', 'project', id, null, row);
+        return { project: parseRow(row, ['goals', 'constraints', 'owners']), audit_id: auditId };
+    }
+    addPerson(ctx, args) {
+        const company = args.company ? this.resolveCompany(args.company) : null;
+        const id = randomUUID();
+        const ts = now();
+        const row = {
+            id,
+            name: args.name,
+            role: args.role ?? null,
+            company_id: company?.id ?? null,
+            relationship_type: args.relationship_type ?? null,
+            communication_preferences: args.communication_preferences ?? null,
+            important_context: args.important_context ?? null,
+            last_interaction_at: null,
+            source_type: ctx.sourceType,
+            source_app: ctx.sourceApp,
+            source_ref: ctx.sourceRef,
+            created_at: ts,
+            updated_at: ts,
+        };
+        this.db
+            .prepare(`INSERT INTO people (id, name, role, company_id, relationship_type, communication_preferences,
+                             important_context, last_interaction_at, source_type, source_app, source_ref,
+                             created_at, updated_at)
+         VALUES (@id, @name, @role, @company_id, @relationship_type, @communication_preferences,
+                 @important_context, @last_interaction_at, @source_type, @source_app, @source_ref,
+                 @created_at, @updated_at)`)
+            .run(row);
+        this.ftsSet('person', id, this.ftsContent('person', row), null);
+        const auditId = this.audit(ctx, 'create', 'person', id, null, row);
+        return { person: row, audit_id: auditId };
+    }
+    addCompany(ctx, args) {
+        const id = randomUUID();
+        const ts = now();
+        const row = {
+            id,
+            name: args.name,
+            industry: args.industry ?? null,
+            stage: args.stage ?? null,
+            priority: args.priority ?? null,
+            notes: args.notes ?? null,
+            source_type: ctx.sourceType,
+            source_app: ctx.sourceApp,
+            source_ref: ctx.sourceRef,
+            created_at: ts,
+            updated_at: ts,
+        };
+        this.db
+            .prepare(`INSERT INTO companies (id, name, industry, stage, priority, notes,
+                                source_type, source_app, source_ref, created_at, updated_at)
+         VALUES (@id, @name, @industry, @stage, @priority, @notes,
+                 @source_type, @source_app, @source_ref, @created_at, @updated_at)`)
+            .run(row);
+        this.ftsSet('company', id, this.ftsContent('company', row), null);
+        const auditId = this.audit(ctx, 'create', 'company', id, null, row);
+        return { company: row, audit_id: auditId };
+    }
+    storeDecision(ctx, args) {
+        const projectId = this.requireProjectId(args.project_id);
+        const id = randomUUID();
+        const ts = now();
+        // Validate the supersede target before writing anything; the old row is
+        // marked only after the new row exists (superseded_by is a FK to it).
+        let oldDecision = null;
+        if (args.supersedes_id) {
+            oldDecision = this.db.prepare(`SELECT * FROM decisions WHERE id = ?`).get(args.supersedes_id);
+            if (!oldDecision)
+                throw new Error(`decision to supersede not found: ${args.supersedes_id}`);
+        }
+        const row = {
+            id,
+            title: args.title,
+            decision: args.decision,
+            rationale: args.rationale ?? null,
+            scope: args.scope ?? null,
+            project_id: projectId,
+            decided_by: args.decided_by ?? null,
+            decided_at: ts,
+            superseded_by: null,
+            confidence: args.confidence ?? 0.8,
+            source_type: ctx.sourceType,
+            source_app: ctx.sourceApp,
+            source_ref: ctx.sourceRef,
+            created_at: ts,
+        };
+        this.db
+            .prepare(`INSERT INTO decisions (id, title, decision, rationale, scope, project_id, decided_by, decided_at,
+                                superseded_by, confidence, source_type, source_app, source_ref, created_at)
+         VALUES (@id, @title, @decision, @rationale, @scope, @project_id, @decided_by, @decided_at,
+                 @superseded_by, @confidence, @source_type, @source_app, @source_ref, @created_at)`)
+            .run(row);
+        this.ftsSet('decision', id, this.ftsContent('decision', row), projectId);
+        if (oldDecision) {
+            this.db.prepare(`UPDATE decisions SET superseded_by = ? WHERE id = ?`).run(id, oldDecision.id);
+            this.ftsDelete('decision', oldDecision.id);
+            this.audit(ctx, 'supersede', 'decision', oldDecision.id, oldDecision, { ...oldDecision, superseded_by: id });
+        }
+        const auditId = this.audit(ctx, 'create', 'decision', id, null, row);
+        return { decision: row, audit_id: auditId };
+    }
+    logEvent(ctx, args) {
+        const projectId = this.requireProjectId(args.project_id);
+        const id = randomUUID();
+        const ts = now();
+        const row = {
+            id,
+            title: args.title ?? null,
+            summary: args.summary,
+            occurred_at: args.occurred_at ?? ts,
+            project_id: projectId,
+            person_ids: toJson(args.person_ids ?? []),
+            company_ids: toJson(args.company_ids ?? []),
+            durability: args.durability ?? 0.7,
+            source_type: ctx.sourceType,
+            source_app: ctx.sourceApp,
+            source_ref: ctx.sourceRef,
+            created_at: ts,
+        };
+        this.db
+            .prepare(`INSERT INTO events (id, title, summary, occurred_at, project_id, person_ids, company_ids,
+                             durability, source_type, source_app, source_ref, created_at)
+         VALUES (@id, @title, @summary, @occurred_at, @project_id, @person_ids, @company_ids,
+                 @durability, @source_type, @source_app, @source_ref, @created_at)`)
+            .run(row);
+        this.ftsSet('event', id, this.ftsContent('event', row), projectId);
+        const auditId = this.audit(ctx, 'create', 'event', id, null, row);
+        return { event: parseRow(row, ['person_ids', 'company_ids']), audit_id: auditId };
+    }
+    updateProjectState(ctx, projectRef, patch) {
+        const project = this.resolveProject(projectRef);
+        if (!project) {
+            throw new Error(`project "${projectRef}" not found — call create_project first`);
+        }
+        const pid = project.id;
+        const wsBefore = parseRow(this.db.prepare(`SELECT * FROM working_state WHERE project_id = ?`).get(pid), ['active_blockers', 'this_week_priorities', 'open_loops']);
+        const before = { project: { ...project }, working_state: wsBefore ?? null };
+        // Top-level project fields
+        const projectPatch = {};
+        if (patch.status !== undefined)
+            projectPatch.status = patch.status;
+        if (patch.goals !== undefined)
+            projectPatch.goals = toJson(patch.goals);
+        if (patch.constraints !== undefined)
+            projectPatch.constraints = toJson(patch.constraints);
+        if (Object.keys(projectPatch).length > 0) {
+            const sets = Object.keys(projectPatch).map((k) => `${k} = @${k}`).join(', ');
+            this.db
+                .prepare(`UPDATE projects SET ${sets}, updated_at = @updated_at WHERE id = @id`)
+                .run({ ...projectPatch, updated_at: now(), id: pid });
+        }
+        // Working state (semi-durable)
+        const ws = {
+            project_id: pid,
+            current_focus: patch.current_focus ?? wsBefore?.current_focus ?? null,
+            active_blockers: toJson(patch.active_blockers ?? wsBefore?.active_blockers ?? []),
+            this_week_priorities: toJson(patch.this_week_priorities ?? wsBefore?.this_week_priorities ?? []),
+            open_loops: toJson(patch.open_loops ?? wsBefore?.open_loops ?? []),
+            last_updated_at: now(),
+        };
+        this.db
+            .prepare(`INSERT INTO working_state (project_id, current_focus, active_blockers, this_week_priorities, open_loops, last_updated_at)
+         VALUES (@project_id, @current_focus, @active_blockers, @this_week_priorities, @open_loops, @last_updated_at)
+         ON CONFLICT(project_id) DO UPDATE SET
+           current_focus = excluded.current_focus,
+           active_blockers = excluded.active_blockers,
+           this_week_priorities = excluded.this_week_priorities,
+           open_loops = excluded.open_loops,
+           last_updated_at = excluded.last_updated_at`)
+            .run(ws);
+        const projectAfter = this.resolveProject(pid);
+        const wsAfter = parseRow(this.db.prepare(`SELECT * FROM working_state WHERE project_id = ?`).get(pid), ['active_blockers', 'this_week_priorities', 'open_loops']);
+        this.ftsSet('project', pid, this.ftsContent('project', {
+            ...projectAfter,
+            goals: toJson(projectAfter.goals),
+            constraints: toJson(projectAfter.constraints),
+        }), pid);
+        const after = { project: projectAfter, working_state: wsAfter };
+        const auditId = this.audit(ctx, 'update', 'working_state', pid, before, after);
+        return { ...after, audit_id: auditId };
+    }
+    savePreference(ctx, args) {
+        let subjectId = null;
+        if (args.subject_type === 'project')
+            subjectId = this.requireProjectId(args.subject_id);
+        else if (args.subject_type === 'person')
+            subjectId = this.resolvePerson(args.subject_id)?.id ?? null;
+        else if (args.subject_type === 'company')
+            subjectId = this.resolveCompany(args.subject_id)?.id ?? null;
+        if (args.subject_type !== 'self' && args.subject_id && !subjectId) {
+            throw new Error(`${args.subject_type} "${args.subject_id}" not found`);
+        }
+        const id = randomUUID();
+        const ts = now();
+        let oldPref = null;
+        if (args.supersedes_id) {
+            oldPref = this.db.prepare(`SELECT * FROM preferences WHERE id = ?`).get(args.supersedes_id);
+            if (!oldPref)
+                throw new Error(`preference to supersede not found: ${args.supersedes_id}`);
+        }
+        const row = {
+            id,
+            subject_type: args.subject_type,
+            subject_id: subjectId,
+            preference_type: args.preference_type ?? null,
+            value: args.value,
+            strength: args.strength ?? 0.8,
+            last_verified_at: ts,
+            superseded_by: null,
+            source_type: ctx.sourceType,
+            source_app: ctx.sourceApp,
+            source_ref: ctx.sourceRef,
+            created_at: ts,
+        };
+        this.db
+            .prepare(`INSERT INTO preferences (id, subject_type, subject_id, preference_type, value, strength,
+                                  last_verified_at, superseded_by, source_type, source_app, source_ref, created_at)
+         VALUES (@id, @subject_type, @subject_id, @preference_type, @value, @strength,
+                 @last_verified_at, @superseded_by, @source_type, @source_app, @source_ref, @created_at)`)
+            .run(row);
+        const projectScope = args.subject_type === 'project' ? subjectId : null;
+        this.ftsSet('preference', id, this.ftsContent('preference', row), projectScope);
+        if (oldPref) {
+            this.db.prepare(`UPDATE preferences SET superseded_by = ? WHERE id = ?`).run(id, oldPref.id);
+            this.ftsDelete('preference', oldPref.id);
+            this.audit(ctx, 'supersede', 'preference', oldPref.id, oldPref, { ...oldPref, superseded_by: id });
+        }
+        const auditId = this.audit(ctx, 'create', 'preference', id, null, row);
+        return { preference: row, audit_id: auditId };
+    }
+    setNextStep(ctx, args) {
+        const projectId = this.requireProjectId(args.project_id);
+        const id = randomUUID();
+        const ts = now();
+        const row = {
+            id,
+            title: args.title,
+            status: args.status ?? 'open',
+            owner: args.owner ?? null,
+            due_at: args.due_at ?? null,
+            project_id: projectId,
+            blocked_by: args.blocked_by ?? null,
+            completed_at: null,
+            source_type: ctx.sourceType,
+            source_app: ctx.sourceApp,
+            source_ref: ctx.sourceRef,
+            created_at: ts,
+            updated_at: ts,
+        };
+        this.db
+            .prepare(`INSERT INTO tasks (id, title, status, owner, due_at, project_id, blocked_by, completed_at,
+                            source_type, source_app, source_ref, created_at, updated_at)
+         VALUES (@id, @title, @status, @owner, @due_at, @project_id, @blocked_by, @completed_at,
+                 @source_type, @source_app, @source_ref, @created_at, @updated_at)`)
+            .run(row);
+        this.ftsSet('task', id, this.ftsContent('task', row), projectId);
+        const auditId = this.audit(ctx, 'create', 'task', id, null, row);
+        return { task: row, audit_id: auditId };
+    }
+    markDone(ctx, taskId) {
+        const before = this.db.prepare(`SELECT * FROM tasks WHERE id = ?`).get(taskId);
+        if (!before)
+            throw new Error(`task not found: ${taskId}`);
+        const ts = now();
+        this.db
+            .prepare(`UPDATE tasks SET status = 'done', completed_at = ?, updated_at = ? WHERE id = ?`)
+            .run(ts, ts, taskId);
+        const after = this.db.prepare(`SELECT * FROM tasks WHERE id = ?`).get(taskId);
+        this.ftsSet('task', taskId, this.ftsContent('task', after), after.project_id);
+        const auditId = this.audit(ctx, 'update', 'task', taskId, before, after);
+        return { task: after, audit_id: auditId };
+    }
+    appendNote(ctx, args) {
+        const projectId = this.requireProjectId(args.project_id);
+        const id = randomUUID();
+        const row = {
+            id,
+            content: args.content,
+            project_id: projectId,
+            tags: toJson(args.tags ?? []),
+            source_type: ctx.sourceType,
+            source_app: ctx.sourceApp,
+            source_ref: ctx.sourceRef,
+            created_at: now(),
+        };
+        this.db
+            .prepare(`INSERT INTO notes (id, content, project_id, tags, source_type, source_app, source_ref, created_at)
+         VALUES (@id, @content, @project_id, @tags, @source_type, @source_app, @source_ref, @created_at)`)
+            .run(row);
+        this.ftsSet('note', id, row.content, projectId);
+        const auditId = this.audit(ctx, 'create', 'note', id, null, row);
+        return { note: parseRow(row, ['tags']), audit_id: auditId };
+    }
+    // ------------------------------------------------------------- reads
+    listProjects() {
+        return this.db
+            .prepare(`SELECT id, name, description, status, updated_at FROM projects ORDER BY updated_at DESC`)
+            .all();
+    }
+    listPeople() {
+        return this.db
+            .prepare(`SELECT p.id, p.name, p.role, c.name AS company, p.relationship_type
+           FROM people p LEFT JOIN companies c ON c.id = p.company_id
+          ORDER BY p.updated_at DESC`)
+            .all();
+    }
+    listCompanies() {
+        return this.db
+            .prepare(`SELECT id, name, industry, stage, priority FROM companies ORDER BY updated_at DESC`)
+            .all();
+    }
+    // The caller is an LLM: it can retry with synonyms, so BM25 keyword search
+    // over typed content covers the retrieval need without embeddings.
+    searchMemories(query, projectRef, limit = 10) {
+        const terms = query.match(/[A-Za-z0-9_]+/g);
+        if (!terms?.length)
+            return [];
+        const match = terms.map((t) => `"${t}"`).join(' OR ');
+        const projectId = projectRef ? this.requireProjectId(projectRef) : null;
+        const sql = projectId
+            ? `SELECT kind, ref_id, content, bm25(memory_fts) AS rank FROM memory_fts
+          WHERE memory_fts MATCH ? AND project_id = ? ORDER BY rank LIMIT ?`
+            : `SELECT kind, ref_id, content, bm25(memory_fts) AS rank FROM memory_fts
+          WHERE memory_fts MATCH ? ORDER BY rank LIMIT ?`;
+        const rows = projectId
+            ? this.db.prepare(sql).all(match, projectId, Math.min(limit, 50))
+            : this.db.prepare(sql).all(match, Math.min(limit, 50));
+        return rows.map((r) => ({ kind: r.kind, id: r.ref_id, content: r.content }));
+    }
+    getProjectContext(ref) {
+        const project = this.resolveProject(ref);
+        if (!project)
+            throw new Error(`project "${ref}" not found — call list_projects to see what exists`);
+        const pid = project.id;
+        return {
+            project,
+            working_state: parseRow(this.db.prepare(`SELECT * FROM working_state WHERE project_id = ?`).get(pid), ['active_blockers', 'this_week_priorities', 'open_loops']) ?? null,
+            recent_decisions: this.recentDecisions(pid, 10),
+            open_tasks: this.db
+                .prepare(`SELECT * FROM tasks WHERE project_id = ? AND status != 'done' AND status != 'cancelled' ORDER BY created_at DESC`)
+                .all(pid),
+            recent_events: this.db
+                .prepare(`SELECT * FROM events WHERE project_id = ? ORDER BY occurred_at DESC LIMIT 10`)
+                .all(pid).map((e) => parseRow(e, ['person_ids', 'company_ids'])),
+            preferences: this.db
+                .prepare(`SELECT * FROM preferences WHERE subject_type = 'project' AND subject_id = ? AND superseded_by IS NULL`)
+                .all(pid),
+            recent_notes: this.db
+                .prepare(`SELECT * FROM notes WHERE project_id = ? ORDER BY created_at DESC LIMIT 5`)
+                .all(pid).map((n) => parseRow(n, ['tags'])),
+        };
+    }
+    getPersonContext(ref) {
+        const person = this.resolvePerson(ref);
+        if (!person)
+            throw new Error(`person "${ref}" not found — call list_people to see what exists`);
+        const company = person.company_id
+            ? this.db.prepare(`SELECT id, name, industry FROM companies WHERE id = ?`).get(person.company_id)
+            : null;
+        return {
+            person,
+            company,
+            preferences: this.db
+                .prepare(`SELECT * FROM preferences WHERE subject_type = 'person' AND subject_id = ? AND superseded_by IS NULL`)
+                .all(person.id),
+            recent_events: this.db
+                .prepare(`SELECT * FROM events WHERE person_ids LIKE ? ORDER BY occurred_at DESC LIMIT 10`)
+                .all(`%"${person.id}"%`).map((e) => parseRow(e, ['person_ids', 'company_ids'])),
+        };
+    }
+    getCompanyContext(ref) {
+        const company = this.resolveCompany(ref);
+        if (!company)
+            throw new Error(`company "${ref}" not found — call list_companies to see what exists`);
+        return {
+            company,
+            people: this.db.prepare(`SELECT id, name, role FROM people WHERE company_id = ?`).all(company.id),
+            preferences: this.db
+                .prepare(`SELECT * FROM preferences WHERE subject_type = 'company' AND subject_id = ? AND superseded_by IS NULL`)
+                .all(company.id),
+            recent_events: this.db
+                .prepare(`SELECT * FROM events WHERE company_ids LIKE ? ORDER BY occurred_at DESC LIMIT 10`)
+                .all(`%"${company.id}"%`).map((e) => parseRow(e, ['person_ids', 'company_ids'])),
+        };
+    }
+    recentDecisions(projectRef, limit = 20) {
+        const projectId = projectRef ? this.requireProjectId(projectRef) : null;
+        const sql = projectId
+            ? `SELECT * FROM decisions WHERE project_id = ? AND superseded_by IS NULL ORDER BY created_at DESC LIMIT ?`
+            : `SELECT * FROM decisions WHERE superseded_by IS NULL ORDER BY created_at DESC LIMIT ?`;
+        return projectId
+            ? this.db.prepare(sql).all(projectId, Math.min(limit, 100))
+            : this.db.prepare(sql).all(Math.min(limit, 100));
+    }
+    openLoops(projectRef) {
+        const projectId = projectRef ? this.requireProjectId(projectRef) : null;
+        const taskSql = projectId
+            ? `SELECT t.*, p.name AS project_name FROM tasks t LEFT JOIN projects p ON p.id = t.project_id
+          WHERE t.status IN ('open','in_progress','blocked') AND t.project_id = ? ORDER BY t.created_at DESC`
+            : `SELECT t.*, p.name AS project_name FROM tasks t LEFT JOIN projects p ON p.id = t.project_id
+          WHERE t.status IN ('open','in_progress','blocked') ORDER BY t.created_at DESC`;
+        const tasks = projectId ? this.db.prepare(taskSql).all(projectId) : this.db.prepare(taskSql).all();
+        const wsSql = projectId
+            ? `SELECT w.*, p.name AS project_name FROM working_state w LEFT JOIN projects p ON p.id = w.project_id WHERE w.project_id = ?`
+            : `SELECT w.*, p.name AS project_name FROM working_state w LEFT JOIN projects p ON p.id = w.project_id`;
+        const states = (projectId ? this.db.prepare(wsSql).all(projectId) : this.db.prepare(wsSql).all());
+        return {
+            open_tasks: tasks,
+            working_state: states
+                .map((s) => parseRow(s, ['active_blockers', 'this_week_priorities', 'open_loops']))
+                .filter((s) => s.open_loops?.length || s.active_blockers?.length || s.current_focus),
+        };
+    }
+    prepareTaskBrief(args) {
+        const brief = { task: args.task };
+        if (args.project_id)
+            brief.project = this.getProjectContext(args.project_id);
+        if (args.person_id)
+            brief.person = this.getPersonContext(args.person_id);
+        brief.self_preferences = this.db
+            .prepare(`SELECT * FROM preferences WHERE subject_type = 'self' AND superseded_by IS NULL`)
+            .all();
+        brief.related_memories = this.searchMemories(args.task, args.project_id ?? null, 8);
+        if (!args.project_id)
+            brief.open_loops = this.openLoops(null);
+        return brief;
+    }
+    // ------------------------------------------------------------- audit + revert
+    recentWrites(limit = 50, offset = 0) {
+        const rows = this.db
+            .prepare(`SELECT * FROM audit_log ORDER BY created_at DESC LIMIT ? OFFSET ?`)
+            .all(Math.min(limit, 200), offset);
+        return rows.map((r) => ({
+            ...r,
+            before_state: r.before_state ? fromJson(r.before_state) : null,
+            after_state: r.after_state ? fromJson(r.after_state) : null,
+            reverted: !!r.reverted,
+        }));
+    }
+    // Soft-revert: the audit row is marked, never deleted, and the revert itself
+    // is a new audit row. create → remove the row; update → restore before_state;
+    // supersede → re-activate the older row.
+    revertWrite(ctx, auditId) {
+        const audit = this.db.prepare(`SELECT * FROM audit_log WHERE id = ?`).get(auditId);
+        if (!audit)
+            throw new Error(`audit entry not found: ${auditId}`);
+        if (audit.reverted)
+            throw new Error(`already reverted: ${auditId}`);
+        if (audit.action === 'revert')
+            throw new Error(`cannot revert a revert entry`);
+        const kind = audit.entity_kind;
+        const id = audit.entity_id;
+        const before = audit.before_state ? fromJson(audit.before_state) : null;
+        const after = audit.after_state ? fromJson(audit.after_state) : null;
+        if (audit.action === 'create') {
+            const table = TABLE[kind];
+            if (table) {
+                this.db.prepare(`DELETE FROM ${table} WHERE id = ?`).run(id);
+                this.ftsDelete(kind, id);
+            }
+        }
+        else if (audit.action === 'supersede') {
+            const table = TABLE[kind];
+            if (table && (kind === 'decision' || kind === 'preference')) {
+                this.db.prepare(`UPDATE ${table} SET superseded_by = NULL WHERE id = ?`).run(id);
+                const row = this.db.prepare(`SELECT * FROM ${table} WHERE id = ?`).get(id);
+                if (row) {
+                    this.ftsSet(kind, id, this.ftsContent(kind, row), row.project_id ?? null);
+                }
+            }
+        }
+        else if (audit.action === 'update' && before) {
+            if (kind === 'task') {
+                this.db
+                    .prepare(`UPDATE tasks SET title = @title, status = @status, owner = @owner, due_at = @due_at,
+                    project_id = @project_id, blocked_by = @blocked_by, completed_at = @completed_at,
+                    updated_at = @updated_at WHERE id = @id`)
+                    .run({ ...before, updated_at: now(), id });
+                this.ftsSet('task', id, this.ftsContent('task', before), before.project_id ?? null);
+            }
+            else if (kind === 'working_state') {
+                const p = before.project;
+                if (p) {
+                    this.db
+                        .prepare(`UPDATE projects SET status = ?, goals = ?, constraints = ?, updated_at = ? WHERE id = ?`)
+                        .run(p.status, toJson(p.goals), toJson(p.constraints), now(), p.id);
+                }
+                const ws = before.working_state;
+                if (ws) {
+                    this.db
+                        .prepare(`INSERT INTO working_state (project_id, current_focus, active_blockers, this_week_priorities, open_loops, last_updated_at)
+               VALUES (?, ?, ?, ?, ?, ?)
+               ON CONFLICT(project_id) DO UPDATE SET
+                 current_focus = excluded.current_focus,
+                 active_blockers = excluded.active_blockers,
+                 this_week_priorities = excluded.this_week_priorities,
+                 open_loops = excluded.open_loops,
+                 last_updated_at = excluded.last_updated_at`)
+                        .run(id, ws.current_focus, toJson(ws.active_blockers), toJson(ws.this_week_priorities), toJson(ws.open_loops), now());
+                }
+                else {
+                    this.db.prepare(`DELETE FROM working_state WHERE project_id = ?`).run(id);
+                }
+            }
+        }
+        this.db.prepare(`UPDATE audit_log SET reverted = 1 WHERE id = ?`).run(auditId);
+        const revertAuditId = this.audit(ctx, 'revert', kind, id, after, before);
+        return { reverted: true, audit_id: auditId, revert_audit_id: revertAuditId };
+    }
+}

package/dist/tools.js

@@ -0,0 +1,294 @@
+const j = (type, extra = {}) => ({ type, ...extra });
+const strArray = { type: 'array', items: { type: 'string' } };
+export function buildTools(store) {
+    return [
+        // ---------------------------------------------------------------- read
+        {
+            name: 'search_memories',
+            description: 'Keyword search (BM25) across all stored memory: decisions, events, preferences, projects, people, companies, tasks, notes. If a query misses, retry with synonyms or related terms. Returns typed entries with their ids.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: j('string', { description: 'Search terms.' }),
+                    project_id: j('string', { description: 'Optional project id or name to scope results.' }),
+                    limit: j('number', { description: 'Max results (default 10).' }),
+                },
+                required: ['query'],
+            },
+            handler: (args) => ({ results: store.searchMemories(args.query, args.project_id ?? null, args.limit ?? 10) }),
+        },
+        {
+            name: 'list_projects',
+            description: 'List all projects with id, name, status. Call this first when unsure which project something belongs to.',
+            inputSchema: { type: 'object', properties: {} },
+            handler: () => ({ projects: store.listProjects() }),
+        },
+        {
+            name: 'list_people',
+            description: 'List all known people with id, name, role, company.',
+            inputSchema: { type: 'object', properties: {} },
+            handler: () => ({ people: store.listPeople() }),
+        },
+        {
+            name: 'list_companies',
+            description: 'List all known companies with id, name, industry.',
+            inputSchema: { type: 'object', properties: {} },
+            handler: () => ({ companies: store.listCompanies() }),
+        },
+        {
+            name: 'get_project_context',
+            description: 'Get full context for a project (by id or name): details, working state, recent decisions, open tasks, recent events, preferences, notes. Call before starting work related to the project.',
+            inputSchema: {
+                type: 'object',
+                properties: { project_id: j('string', { description: 'Project id or exact name.' }) },
+                required: ['project_id'],
+            },
+            handler: (args) => store.getProjectContext(args.project_id),
+        },
+        {
+            name: 'get_person_context',
+            description: 'Get full context for a person (by id or name): profile, preferences, recent events.',
+            inputSchema: {
+                type: 'object',
+                properties: { person_id: j('string', { description: 'Person id or exact name.' }) },
+                required: ['person_id'],
+            },
+            handler: (args) => store.getPersonContext(args.person_id),
+        },
+        {
+            name: 'get_company_context',
+            description: 'Get full context for a company (by id or name): profile, people, preferences, recent events.',
+            inputSchema: {
+                type: 'object',
+                properties: { company_id: j('string', { description: 'Company id or exact name.' }) },
+                required: ['company_id'],
+            },
+            handler: (args) => store.getCompanyContext(args.company_id),
+        },
+        {
+            name: 'get_recent_decisions',
+            description: 'Most recent non-superseded decisions, optionally scoped by project (id or name).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: j('string'),
+                    limit: j('number', { description: 'Default 20.' }),
+                },
+            },
+            handler: (args) => ({ decisions: store.recentDecisions(args.project_id ?? null, args.limit ?? 20) }),
+        },
+        {
+            name: 'get_open_loops',
+            description: 'Open tasks plus per-project open loops and active blockers from working state.',
+            inputSchema: {
+                type: 'object',
+                properties: { project_id: j('string') },
+            },
+            handler: (args) => store.openLoops(args.project_id ?? null),
+        },
+        {
+            name: 'prepare_task_brief',
+            description: 'Build a context packet for a task — project state, decisions, open loops, related memories. Call this before doing real work so you start with full context.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    task: j('string', { description: 'What you are about to do.' }),
+                    project_id: j('string'),
+                    person_id: j('string'),
+                },
+                required: ['task'],
+            },
+            handler: (args) => store.prepareTaskBrief({ task: args.task, project_id: args.project_id ?? null, person_id: args.person_id ?? null }),
+        },
+        // ---------------------------------------------------------------- write
+        {
+            name: 'create_project',
+            description: 'Create a project — the top-level scope for decisions, tasks, events, and working state.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: j('string'),
+                    description: j('string'),
+                    status: j('string'),
+                    goals: strArray,
+                    constraints: strArray,
+                    owners: strArray,
+                },
+                required: ['name'],
+            },
+            handler: (args, ctx) => store.createProject(ctx, args),
+        },
+        {
+            name: 'add_person',
+            description: 'Add a person worth remembering (colleague, client, stakeholder).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: j('string'),
+                    role: j('string'),
+                    company: j('string', { description: 'Company id or name (must exist).' }),
+                    relationship_type: j('string'),
+                    communication_preferences: j('string'),
+                    important_context: j('string'),
+                },
+                required: ['name'],
+            },
+            handler: (args, ctx) => store.addPerson(ctx, args),
+        },
+        {
+            name: 'add_company',
+            description: 'Add a company (client, partner, account).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: j('string'),
+                    industry: j('string'),
+                    stage: j('string'),
+                    priority: j('string'),
+                    notes: j('string'),
+                },
+                required: ['name'],
+            },
+            handler: (args, ctx) => store.addCompany(ctx, args),
+        },
+        {
+            name: 'store_decision',
+            description: 'Persist a durable decision. Use when a real choice was made — direction, plan, trade-off — not for speculation or drafts. Pass supersedes_id when this replaces an earlier decision.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    title: j('string'),
+                    decision: j('string', { description: 'Concise statement of what was decided.' }),
+                    rationale: j('string'),
+                    scope: j('string'),
+                    project_id: j('string', { description: 'Project id or name (must exist).' }),
+                    confidence: j('number', { description: '0..1 confidence in the decision.' }),
+                    supersedes_id: j('string', { description: 'Id of an earlier decision this replaces.' }),
+                },
+                required: ['title', 'decision'],
+            },
+            handler: (args, ctx) => store.storeDecision(ctx, args),
+        },
+        {
+            name: 'log_event',
+            description: 'Log a durable event (meeting outcome, milestone, signal). Do not log exploratory chatter.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    summary: j('string'),
+                    title: j('string'),
+                    occurred_at: j('string', { description: 'ISO timestamp; defaults to now.' }),
+                    project_id: j('string'),
+                    person_ids: strArray,
+                    company_ids: strArray,
+                    durability: j('number', { description: '0..1, how long this stays relevant.' }),
+                },
+                required: ['summary'],
+            },
+            handler: (args, ctx) => store.logEvent(ctx, args),
+        },
+        {
+            name: 'update_project_state',
+            description: 'Update working state for a project: current_focus, active_blockers, this_week_priorities, open_loops. Can also update top-level status/goals/constraints.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: j('string', { description: 'Project id or name.' }),
+                    status: j('string'),
+                    current_focus: j('string'),
+                    active_blockers: strArray,
+                    this_week_priorities: strArray,
+                    open_loops: strArray,
+                    goals: strArray,
+                    constraints: strArray,
+                },
+                required: ['project_id'],
+            },
+            handler: (args, ctx) => {
+                const { project_id, ...patch } = args;
+                return store.updateProjectState(ctx, project_id, patch);
+            },
+        },
+        {
+            name: 'save_preference',
+            description: 'Record a learned preference about a person, company, project, or self (e.g. "prefers concise updates"). Pass supersedes_id when this replaces an earlier preference.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    subject_type: j('string', { enum: ['person', 'company', 'project', 'self'] }),
+                    subject_id: j('string', { description: 'Id or name of the subject; omit for self.' }),
+                    preference_type: j('string'),
+                    value: j('string'),
+                    strength: j('number'),
+                    supersedes_id: j('string'),
+                },
+                required: ['subject_type', 'value'],
+            },
+            handler: (args, ctx) => store.savePreference(ctx, args),
+        },
+        {
+            name: 'set_next_step',
+            description: 'Create a next step / task. Use when a concrete next action becomes clear.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    title: j('string'),
+                    status: j('string', { enum: ['open', 'in_progress', 'blocked'] }),
+                    owner: j('string'),
+                    due_at: j('string'),
+                    project_id: j('string'),
+                    blocked_by: j('string', { description: 'Id of a blocking task.' }),
+                },
+                required: ['title'],
+            },
+            handler: (args, ctx) => store.setNextStep(ctx, args),
+        },
+        {
+            name: 'mark_done',
+            description: 'Mark an existing task as done.',
+            inputSchema: {
+                type: 'object',
+                properties: { task_id: j('string') },
+                required: ['task_id'],
+            },
+            handler: (args, ctx) => store.markDone(ctx, args.task_id),
+        },
+        {
+            name: 'append_note',
+            description: 'Free-form fallback note. Prefer the typed tools (store_decision, log_event, save_preference) when one fits.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    content: j('string'),
+                    project_id: j('string'),
+                    tags: strArray,
+                },
+                required: ['content'],
+            },
+            handler: (args, ctx) => store.appendNote(ctx, args),
+        },
+        // ---------------------------------------------------------------- audit
+        {
+            name: 'list_recent_writes',
+            description: 'List recent memory writes with before/after state, source app, and revert status. This is the audit trail — use it to show the user what has been remembered.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    limit: j('number', { description: 'Default 50, max 200.' }),
+                    offset: j('number'),
+                },
+            },
+            handler: (args) => ({ writes: store.recentWrites(args.limit ?? 50, args.offset ?? 0) }),
+        },
+        {
+            name: 'revert_write',
+            description: 'Undo a prior memory write by its audit_id (from list_recent_writes or any write result). Soft-revert: the audit entry is preserved and the revert itself is audited.',
+            inputSchema: {
+                type: 'object',
+                properties: { audit_id: j('string') },
+                required: ['audit_id'],
+            },
+            handler: (args, ctx) => store.revertWrite(ctx, args.audit_id),
+        },
+    ];
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "smaran",
+  "version": "0.1.0",
+  "description": "Smaran (Sanskrit: remembrance) — local-first professional memory for AI agents over MCP. Typed writes, append-only audit log, and an undo button. No Docker, no API keys, no account.",
+  "type": "module",
+  "bin": {
+    "smaran": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node test/e2e.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "agent",
+    "claude",
+    "audit",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "better-sqlite3": "^11.10.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^20.17.0",
+    "typescript": "^5.6.3"
+  }
+}