@gorajing/zuun 0.1.1

package/dist/mcp.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const zod_1 = require("zod");
+const db_1 = require("./lib/db");
+const store_1 = require("./lib/store");
+const entry_io_1 = require("./lib/entry-io");
+const id_1 = require("./lib/id");
+const search_1 = require("./lib/search");
+const embed_provider_1 = require("./lib/embed-provider");
+const embed_1 = require("./lib/embed");
+const entry_1 = require("./lib/entry");
+const tags_1 = require("./lib/tags");
+const dedup_1 = require("./lib/dedup");
+const project_1 = require("./lib/project");
+const log_1 = require("./lib/log");
+const SOURCE = entry_1.EntrySource.safeParse(process.env.ZUUN_MCP_SOURCE).success
+    ? process.env.ZUUN_MCP_SOURCE
+    : "claude-code";
+const RememberInput = zod_1.z.object({
+    body: zod_1.z.string().min(1, "body must not be empty"),
+    kind: entry_1.EntryKind.default("observation"),
+    tags: zod_1.z.array(zod_1.z.string()).default([]),
+    stance: zod_1.z.string().optional(),
+    related: zod_1.z.array(zod_1.z.string()).default([]),
+    origin: zod_1.z.string().optional(),
+    project: zod_1.z.string().optional(),
+});
+const ContextForInput = zod_1.z.object({
+    task: zod_1.z.string().min(1, "task must not be empty"),
+    limit: zod_1.z.number().int().positive().max(50).default(8),
+});
+const REMEMBER_DESC = `Save a durable insight from this session so future sessions can recall it.
+
+WHEN TO CALL: Something you just decided, observed, or learned that a new session would have to re-derive — an architectural choice, a "we don't do X because Y," a rule of thumb, a commitment to future-self, or an external fact worth preserving. Call as soon as the thing is true; you don't have to batch.
+
+WHEN NOT TO CALL: (1) Ephemeral task state — use your own notes. (2) Content already in the codebase — code is its own memory. (3) Unverified speculation — capture after confirming.
+
+INPUT SHAPE: One self-contained claim per call. "Local-first beats cloud-first for portability because tar is the moat." — not a paragraph, not a list. If you have five things to remember, make five calls.
+
+KINDS: "decision" (a choice with reasoning), "observation" (something noticed about how the world works), "pattern" (a reusable approach), "commitment" (a promise to future-self), "reference" (a durable context snippet).
+
+OPTIONAL \`origin\`: Pass the file path, git sha, PR number, or session marker this entry came from — lets future retrieval cite the source. Use it when the memory is tied to a specific artifact.
+
+PROJECT SCOPING: The \`project\` field is auto-populated from the MCP server's cwd (git root, or pwd). This scopes the entry so SessionStart / context_for retrieve it only for sessions in the same project. Override \`project\` only if the memory belongs to a different project than the current session's cwd — e.g., a cross-repo observation.
+
+OUTPUT: The generated entry id, kind, and echoed body on success. If an identical body was remembered in the last 10 minutes, returns "already remembered <id>" without duplicating.`;
+const CONTEXT_FOR_DESC = `Surface the most relevant past entries for what you're working on right now.
+
+WHEN TO CALL: At the start of a new task, or when switching context. Once per context switch — not repeatedly inside the same task. Results are stable-enough that re-querying wastes attention budget.
+
+INPUT SHAPE: Free-form, specific description of the current work. "picking between SQLite and Postgres for session storage" beats "databases". More specific phrasing retrieves more specific matches.
+
+SCOPING: Retrieval is automatically scoped to the current project (resolved from the server's cwd). Global entries (captured outside any git repo) are always included — they apply everywhere. Entries from other projects are excluded. You don't control this; it's structural.
+
+OUTPUT: A markdown list of up to \`limit\` entries. Each line shows id, kind, relative age, and body. If no matching prior context exists, returns "no prior context" — treat that as signal, not an error. The entries you see are the entries your past self already thought were worth remembering; cite their ids when referencing them.`;
+async function main() {
+    const server = new index_js_1.Server({ name: "zuun", version: "0.1.1" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "remember",
+                description: REMEMBER_DESC,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        body: { type: "string", description: "The content to remember — one self-contained claim." },
+                        kind: {
+                            type: "string",
+                            enum: ["decision", "observation", "pattern", "commitment", "reference"],
+                            description: "Defaults to observation if omitted.",
+                        },
+                        tags: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Freeform tags. Normalized to lowercase-dashed.",
+                        },
+                        stance: {
+                            type: "string",
+                            description: "Optional one-line directional claim, assertable as true or false.",
+                        },
+                        related: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional entry IDs this one builds on. Soft refs; not validated.",
+                        },
+                        origin: {
+                            type: "string",
+                            description: "Optional provenance: file path, git sha, PR number, or session marker. Lets future retrieval cite sources.",
+                        },
+                        project: {
+                            type: "string",
+                            description: "Optional absolute path scoping this entry to a project. Auto-populated from the server's cwd (git root or pwd) if omitted — override only if the memory genuinely belongs to a different project than the session's cwd.",
+                        },
+                    },
+                    required: ["body"],
+                },
+            },
+            {
+                name: "context_for",
+                description: CONTEXT_FOR_DESC,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        task: { type: "string", description: "What you're working on, in your own words." },
+                        limit: { type: "number", description: "Max results. Default 8, max 50.", default: 8 },
+                    },
+                    required: ["task"],
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
+        if (req.params.name === "remember")
+            return handleRemember(req.params.arguments);
+        if (req.params.name === "context_for")
+            return handleContextFor(req.params.arguments);
+        return {
+            content: [{ type: "text", text: `unknown tool: ${req.params.name}` }],
+            isError: true,
+        };
+    });
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+async function handleRemember(args) {
+    const input = RememberInput.parse(args);
+    const now = new Date();
+    const db = (0, db_1.openDb)();
+    try {
+        const existing = (0, dedup_1.findRecentDuplicate)(db, input.body, now);
+        if (existing) {
+            (0, log_1.appendLog)("remember.dedup", { id: existing });
+            return {
+                content: [
+                    { type: "text", text: `already remembered ${existing} (same body within 10 minutes)` },
+                ],
+            };
+        }
+        const id = (0, id_1.newEntryId)(input.body, now);
+        const entry = {
+            id,
+            created: now.toISOString(),
+            body: input.body,
+            kind: input.kind,
+            source: SOURCE,
+            tags: (0, tags_1.normalizeTags)(input.tags),
+            related: input.related,
+            stance: input.stance,
+            origin: input.origin,
+            project: input.project ?? (0, project_1.resolveProject)(),
+        };
+        (0, entry_io_1.writeEntry)(entry);
+        (0, store_1.upsertEntry)(db, entry);
+        (0, log_1.appendLog)("remember", { id, kind: entry.kind, tags: entry.tags });
+        // Fire-and-forget embed: search works without it; rerun via `zuun embed`.
+        void embed_provider_1.defaultProvider
+            .embed(entry.body)
+            .then((vec) => {
+            if (!vec)
+                return;
+            const db2 = (0, db_1.openDb)();
+            try {
+                (0, embed_1.setEmbedding)(db2, id, vec);
+            }
+            finally {
+                db2.close();
+            }
+        })
+            .catch(() => { });
+        const tagLine = entry.tags.length ? ` · tags: ${entry.tags.join(", ")}` : "";
+        return {
+            content: [
+                { type: "text", text: `saved ${id} (${entry.kind}${tagLine})\n${entry.body}` },
+            ],
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+async function handleContextFor(args) {
+    const input = ContextForInput.parse(args);
+    const db = (0, db_1.openDb)();
+    try {
+        const project = (0, project_1.resolveProject)();
+        const qVec = await embed_provider_1.defaultProvider.embed(input.task);
+        const results = (0, search_1.search)(db, {
+            query: input.task,
+            queryVec: qVec ?? undefined,
+            limit: input.limit,
+            project: project ?? undefined,
+        });
+        (0, log_1.appendLog)("context_for", { task: input.task.slice(0, 120), project, hits: results.length });
+        const text = results.length === 0 ? "no prior context" : formatResults(results);
+        return { content: [{ type: "text", text }] };
+    }
+    finally {
+        db.close();
+    }
+}
+function formatResults(results) {
+    const lines = [`Found ${results.length} entries:\n`];
+    const now = Date.now();
+    for (const r of results) {
+        const age = relativeAge(now - new Date(r.entry.created).getTime());
+        const tags = r.entry.tags.length ? ` · tags: ${r.entry.tags.join(", ")}` : "";
+        lines.push(`- ${r.entry.id} · ${r.entry.kind} · ${age}${tags}`);
+        lines.push(`  ${r.entry.body.replace(/\n/g, " ")}`);
+    }
+    return lines.join("\n");
+}
+function relativeAge(ms) {
+    const d = Math.floor(ms / 86_400_000);
+    if (d < 1)
+        return "today";
+    if (d < 2)
+        return "yesterday";
+    if (d < 14)
+        return `${d}d ago`;
+    if (d < 60)
+        return `${Math.floor(d / 7)}w ago`;
+    return `${Math.floor(d / 30)}mo ago`;
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/scripts/reindex.js

@@ -0,0 +1,71 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reindex = reindex;
+const fs = __importStar(require("fs"));
+const db_1 = require("../lib/db");
+const entry_io_1 = require("../lib/entry-io");
+const store_1 = require("../lib/store");
+const paths_1 = require("../lib/paths");
+const log_1 = require("../lib/log");
+function reindex() {
+    if (fs.existsSync((0, paths_1.dbPath)()))
+        fs.rmSync((0, paths_1.dbPath)());
+    const db = (0, db_1.openDb)();
+    const failed = [];
+    let indexed = 0;
+    for (const id of (0, entry_io_1.listEntryIds)()) {
+        try {
+            (0, store_1.upsertEntry)(db, (0, entry_io_1.readEntry)(id));
+            indexed++;
+        }
+        catch (err) {
+            failed.push(`${id}: ${err.message}`);
+        }
+    }
+    db.close();
+    (0, log_1.appendLog)("reindex", { indexed, failed: failed.length });
+    return { indexed, failed };
+}
+if (require.main === module) {
+    const r = reindex();
+    console.log(`indexed ${r.indexed} entries`);
+    if (r.failed.length > 0) {
+        console.error(`failed: ${r.failed.length}`);
+        for (const line of r.failed)
+            console.error(`  ${line}`);
+        process.exit(1);
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@gorajing/zuun",
+  "version": "0.1.1",
+  "description": "Persistent memory for AI-assisted work — local-first markdown + SQLite, hybrid search, Claude Code plugin.",
+  "author": "Jin Choi",
+  "license": "MIT",
+  "homepage": "https://github.com/gorajing/zuun",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gorajing/zuun.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gorajing/zuun/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "memory",
+    "ai-agents",
+    "local-first",
+    "typescript",
+    "plugin"
+  ],
+  "type": "commonjs",
+  "engines": {
+    "node": "20.x || 22.x"
+  },
+  "bin": {
+    "zuun": "bin/zuun.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx src/mcp.ts",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "cli": "tsx src/cli.ts",
+    "reindex": "tsx src/scripts/reindex.ts",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "better-sqlite3": "^12.8.0",
+    "gray-matter": "^4.0.3",
+    "sqlite-vec": "^0.1.7",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}