meminbox 0.0.0-stage → 0.2.1

package/dist/extract.js

@@ -0,0 +1,53 @@
+/**
+ * The "mem0 as a component" piece — and ONLY that piece.
+ *
+ * Extraction turns raw material (a conversation, a session log) into
+ * candidate memories. Candidates are written to the INBOX, never directly
+ * to active memory: extraction is fallible, and shared memory amplifies
+ * errors. A human (or an explicit promote call) is the quality gate.
+ *
+ * This implementation is deliberately small and swappable. If a dedicated
+ * extractor (mem0, a local model, ...) proves better on your own data,
+ * replace `extractCandidates` behind this interface — nothing else changes,
+ * because extracted facts are not the source of truth; documents are.
+ */
+export async function extractCandidates(cfg, rawText, opts = {}) {
+    if (!cfg.openaiApiKey) {
+        // No LLM configured: keep the raw material as a single inbox candidate
+        // rather than pretending extraction happened.
+        return [{ title: "Unprocessed note", contentMd: rawText }];
+    }
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${cfg.openaiApiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            model: opts.model ?? process.env.EXTRACT_MODEL ?? "gpt-4o-mini",
+            response_format: { type: "json_object" },
+            messages: [
+                {
+                    role: "system",
+                    content: "Extract durable knowledge worth remembering across future sessions: " +
+                        "decisions and their reasons, procedures, stable facts about the user or a project. " +
+                        "Skip small talk, transient status, and anything already generic. " +
+                        'Return JSON: {"items": [{"title": string, "content": string}]} where content is ' +
+                        "self-contained Markdown that makes sense without the original conversation. " +
+                        "Preserve concrete details (names, paths, versions, dates). If nothing is durable, return an empty list.",
+                },
+                { role: "user", content: rawText },
+            ],
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`Extraction request failed: ${res.status} ${await res.text()}`);
+    }
+    const json = (await res.json());
+    const parsed = JSON.parse(json.choices[0]?.message.content ?? "{}");
+    return (parsed.items ?? []).map((i) => ({
+        title: i.title,
+        contentMd: i.content,
+    }));
+}
+//# sourceMappingURL=extract.js.map

package/dist/init.js

@@ -0,0 +1,155 @@
+import { createInterface } from "node:readline/promises";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createClient } from "@supabase/supabase-js";
+import pg from "pg";
+import { formatDotEnv, meminboxEnvPath, meminboxHome } from "./dotenv.js";
+function parseFlags(argv) {
+    const get = (name) => {
+        const i = argv.indexOf(`--${name}`);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    return {
+        url: get("url") ?? process.env.SUPABASE_URL,
+        serviceKey: get("service-key") ?? process.env.SUPABASE_SERVICE_ROLE_KEY,
+        databaseUrl: get("database-url") ?? process.env.DATABASE_URL,
+        openaiKey: get("openai-key") ?? process.env.OPENAI_API_KEY,
+        actor: get("actor"),
+        project: get("project"),
+        noMigrate: argv.includes("--no-migrate"),
+        force: argv.includes("--force"),
+        yes: argv.includes("--yes"),
+    };
+}
+async function promptSecret(query) {
+    if (!process.stdin.isTTY) {
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        const answer = await rl.question(query);
+        rl.close();
+        return answer.trim();
+    }
+    process.stderr.write(query);
+    return new Promise((resolve) => {
+        const stdin = process.stdin;
+        stdin.setRawMode(true);
+        stdin.resume();
+        let value = "";
+        const onData = (buf) => {
+            const ch = buf.toString("utf8");
+            if (ch === "\n" || ch === "\r" || ch === "\u0004") {
+                stdin.setRawMode(false);
+                stdin.pause();
+                stdin.removeListener("data", onData);
+                process.stderr.write("\n");
+                resolve(value.trim());
+            }
+            else if (ch === "\u0003") {
+                process.exit(130);
+            }
+            else if (ch === "\u007f") {
+                value = value.slice(0, -1);
+            }
+            else {
+                value += ch;
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+function migrationDir() {
+    // Works from both src/ (tsx) and dist/ (built): both sit one level
+    // below the package root, next to supabase/migrations.
+    return fileURLToPath(new URL("../supabase/migrations/", import.meta.url));
+}
+export function listMigrationSql() {
+    const dir = migrationDir();
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".sql"))
+        .sort()
+        .map((name) => ({ name, sql: readFileSync(`${dir}${name}`, "utf8") }));
+}
+async function applyMigrations(databaseUrl) {
+    const client = new pg.Client({ connectionString: databaseUrl });
+    await client.connect();
+    try {
+        for (const m of listMigrationSql()) {
+            await client.query(m.sql);
+            console.log(`applied migration ${m.name}`);
+        }
+    }
+    finally {
+        await client.end();
+    }
+}
+export async function runInit(argv) {
+    const opts = parseFlags(argv);
+    const envPath = meminboxEnvPath();
+    if (existsSync(envPath) && !opts.force) {
+        if (opts.yes) {
+            throw new Error(`${envPath} already exists. Re-run with --force to overwrite.`);
+        }
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        const answer = await rl.question(`${envPath} already exists. Overwrite? [y/N] `);
+        rl.close();
+        if (!/^y(es)?$/i.test(answer.trim())) {
+            console.log("aborted — existing config kept");
+            return;
+        }
+    }
+    let { url, serviceKey, databaseUrl, openaiKey } = opts;
+    if (!opts.yes) {
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        if (!url)
+            url = (await rl.question("Supabase project URL (https://….supabase.co): ")).trim();
+        rl.close();
+        if (!serviceKey)
+            serviceKey = await promptSecret("Supabase service role key (input hidden): ");
+        if (!databaseUrl && !opts.noMigrate) {
+            databaseUrl = await promptSecret("Postgres connection string for migrations (optional, Enter to skip — you can paste the SQL in the SQL Editor instead): ");
+            if (!databaseUrl)
+                databaseUrl = undefined;
+        }
+        if (!openaiKey) {
+            const rl2 = createInterface({ input: process.stdin, output: process.stderr });
+            openaiKey = (await rl2.question("OpenAI API key for embeddings (optional, Enter to skip): ")).trim() || undefined;
+            rl2.close();
+        }
+    }
+    if (!url || !serviceKey) {
+        throw new Error("SUPABASE_URL and the service role key are required. Pass --url / --service-key or run interactively.");
+    }
+    if (!/^https:\/\//.test(url))
+        throw new Error("Supabase URL must start with https://");
+    if (databaseUrl && !opts.noMigrate) {
+        await applyMigrations(databaseUrl);
+    }
+    else {
+        console.log("\nSchema not applied automatically. Paste the migration SQL into your Supabase SQL Editor:\n" +
+            listMigrationSql().map((m) => `  - supabase/migrations/${m.name} (in the meminbox package)`).join("\n") +
+            "\n");
+    }
+    mkdirSync(meminboxHome(), { recursive: true, mode: 0o700 });
+    const values = {
+        SUPABASE_URL: url,
+        SUPABASE_SERVICE_ROLE_KEY: serviceKey,
+        MEMORY_ACTOR: opts.actor ?? "cli",
+        MEMORY_DEFAULT_PROJECT: opts.project ?? "default",
+    };
+    if (openaiKey)
+        values.OPENAI_API_KEY = openaiKey;
+    writeFileSync(envPath, formatDotEnv(values), { mode: 0o600 });
+    console.log(`wrote ${envPath} (mode 0600; database URL was not saved)`);
+    // Smoke test: proves credentials AND schema in one round trip.
+    const db = createClient(url, serviceKey, { auth: { persistSession: false } });
+    const { error } = await db.from("projects").select("slug").limit(1);
+    if (error) {
+        console.log(`\nConnected to Supabase, but the meminbox schema is not reachable (${error.message}).\n` +
+            "If you skipped migrations, apply the SQL first, then verify with: meminbox list");
+        return;
+    }
+    console.log("\nSetup complete. Next steps:");
+    console.log("  meminbox configure-agent --tool claude-code   # or codex / cursor / claude-desktop");
+    console.log("  meminbox add --title 'First memory' --text '…' --active");
+    console.log("  meminbox search 'First memory'");
+}
+//# sourceMappingURL=init.js.map

package/dist/mcp/server.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig } from "../config.js";
+import { createDb } from "../db.js";
+import { extractCandidates } from "../extract.js";
+import { MemoryService } from "../memory.js";
+/**
+ * Unified memory interface for agents.
+ *
+ * Every MCP client (Claude Code, Codex, Cursor, ...) pointed at the same
+ * Supabase project reads and writes the same memory. Writes default to the
+ * inbox; search reads active memory. Set MEMORY_ACTOR per client so the
+ * audit log and provenance show WHICH agent wrote what.
+ */
+const cfg = loadConfig();
+const memory = new MemoryService(cfg, createDb(cfg));
+const server = new McpServer({ name: "meminbox", version: "0.2.0" });
+function text(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof payload === "string" ? payload : JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+}
+server.registerTool("memory_search", {
+    description: "Search shared active memory across all agents. Returns the most relevant documents (hybrid keyword + vector when embeddings are configured).",
+    inputSchema: {
+        query: z.string().min(1),
+        limit: z.number().int().min(1).max(50).optional(),
+        includeInbox: z.boolean().optional(),
+    },
+}, async ({ query, limit, includeInbox }) => {
+    const active = await memory.search(query, { limit });
+    if (!includeInbox)
+        return text(active);
+    const inbox = await memory.search(query, { limit, status: "inbox" });
+    return text({ active, inbox });
+});
+server.registerTool("memory_read", {
+    description: "Read one memory document in full by its id.",
+    inputSchema: { id: z.string().uuid() },
+}, async ({ id }) => {
+    const doc = await memory.getDocument(id);
+    return text(doc ?? "not found");
+});
+server.registerTool("memory_write", {
+    description: "Write a memory document. It lands in the INBOX by default — it becomes trusted, searchable-by-default memory only after memory_promote. Pass status 'active' only for content a human has already reviewed.",
+    inputSchema: {
+        title: z.string().min(1),
+        content: z.string().min(1),
+        project: z.string().optional(),
+        status: z.enum(["inbox", "active"]).optional(),
+        source: z.string().optional(),
+    },
+}, async ({ title, content, project, status, source }) => {
+    const doc = await memory.writeDocument({
+        title,
+        contentMd: content,
+        projectSlug: project,
+        status,
+        provenance: { source: source ?? "agent-write" },
+    });
+    return text({ id: doc.id, status: doc.status, title: doc.title });
+});
+server.registerTool("memory_extract", {
+    description: "Extract durable knowledge candidates from raw text (e.g. a session transcript) and file them in the inbox for review. Extraction never writes active memory directly.",
+    inputSchema: {
+        text: z.string().min(1),
+        project: z.string().optional(),
+    },
+}, async ({ text: raw, project }) => {
+    const candidates = await extractCandidates(cfg, raw);
+    const written = [];
+    for (const c of candidates) {
+        const doc = await memory.writeDocument({
+            title: c.title,
+            contentMd: c.contentMd,
+            projectSlug: project,
+            provenance: { source: "extraction" },
+        });
+        written.push({ id: doc.id, title: doc.title });
+    }
+    return text({ filedToInbox: written });
+});
+server.registerTool("memory_promote", {
+    description: "Promote an inbox document to active (trusted) memory, or archive a document. This is the quality gate for shared memory.",
+    inputSchema: {
+        id: z.string().uuid(),
+        action: z.enum(["promote", "archive"]),
+    },
+}, async ({ id, action }) => {
+    const doc = await memory.setStatus(id, action === "promote" ? "active" : "archived");
+    return text({ id: doc.id, status: doc.status });
+});
+server.registerTool("memory_list", {
+    description: "List recent memory documents, optionally filtered by status.",
+    inputSchema: {
+        status: z.enum(["inbox", "active", "archived"]).optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+    },
+}, async ({ status, limit }) => {
+    const docs = await memory.listDocuments({ status, limit });
+    return text(docs.map((d) => ({
+        id: d.id,
+        title: d.title,
+        status: d.status,
+        source_agent: d.source_agent,
+        updated_at: d.updated_at,
+    })));
+});
+server.registerTool("memory_projects", {
+    description: "List memory projects (namespaces).",
+    inputSchema: {},
+}, async () => text(await memory.listProjects()));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=server.js.map

package/dist/memory.js

@@ -0,0 +1,207 @@
+import { chunkMarkdown } from "./chunk.js";
+import { embedBatch, embedText } from "./embeddings.js";
+/** pgvector accepts the "[1,2,3]" text literal; use it for inserts and RPC. */
+function toVectorLiteral(vec) {
+    return `[${vec.join(",")}]`;
+}
+export class MemoryService {
+    cfg;
+    db;
+    constructor(cfg, db) {
+        this.cfg = cfg;
+        this.db = db;
+    }
+    // -- projects -------------------------------------------------------------
+    async ensureProject(slug, name) {
+        const { data, error } = await this.db
+            .from("projects")
+            .upsert({ slug, name: name ?? slug }, { onConflict: "slug" })
+            .select("id")
+            .single();
+        if (error)
+            throw new Error(`ensureProject failed: ${error.message}`);
+        return data.id;
+    }
+    async listProjects() {
+        const { data, error } = await this.db
+            .from("projects")
+            .select("slug, name")
+            .order("slug");
+        if (error)
+            throw new Error(`listProjects failed: ${error.message}`);
+        return data ?? [];
+    }
+    // -- writes ---------------------------------------------------------------
+    /**
+     * Write a memory document. Default status is "inbox": agent writes are
+     * NOT trusted memory until promoted. That staging step is the guardrail
+     * against one agent's mistake becoming every agent's fact.
+     */
+    async writeDocument(input) {
+        const projectId = await this.ensureProject(input.projectSlug ?? this.cfg.defaultProject);
+        const provenance = {
+            agent: this.cfg.actor,
+            source: "manual",
+            ...input.provenance,
+        };
+        const { data, error } = await this.db
+            .from("documents")
+            .insert({
+            project_id: projectId,
+            title: input.title,
+            content_md: input.contentMd,
+            status: input.status ?? "inbox",
+            source_agent: provenance.agent ?? null,
+            provenance,
+        })
+            .select("*")
+            .single();
+        if (error)
+            throw new Error(`writeDocument failed: ${error.message}`);
+        const doc = data;
+        await this.indexDocument(doc);
+        await this.audit("write", doc.id, { status: doc.status });
+        return doc;
+    }
+    async setStatus(id, status) {
+        const { data, error } = await this.db
+            .from("documents")
+            .update({ status, updated_at: new Date().toISOString() })
+            .eq("id", id)
+            .select("*")
+            .single();
+        if (error)
+            throw new Error(`setStatus failed: ${error.message}`);
+        await this.audit(status === "active" ? "promote" : status === "archived" ? "archive" : "demote", id, { status });
+        return data;
+    }
+    async getDocument(id) {
+        const { data, error } = await this.db
+            .from("documents")
+            .select("*")
+            .eq("id", id)
+            .maybeSingle();
+        if (error)
+            throw new Error(`getDocument failed: ${error.message}`);
+        return data ?? null;
+    }
+    async listDocuments(opts = {}) {
+        let q = this.db
+            .from("documents")
+            .select("*")
+            .order("updated_at", { ascending: false })
+            .limit(opts.limit ?? 50);
+        if (opts.status)
+            q = q.eq("status", opts.status);
+        const { data, error } = await q;
+        if (error)
+            throw new Error(`listDocuments failed: ${error.message}`);
+        return (data ?? []);
+    }
+    // -- derived index ----------------------------------------------------------
+    /** Rebuild the chunk/embedding index for one document. Safe to re-run. */
+    async indexDocument(doc) {
+        const chunks = chunkMarkdown(`${doc.title}\n\n${doc.content_md}`);
+        const embeddings = await embedBatch(this.cfg, chunks);
+        const { error: delError } = await this.db
+            .from("document_chunks")
+            .delete()
+            .eq("document_id", doc.id);
+        if (delError)
+            throw new Error(`indexDocument delete failed: ${delError.message}`);
+        if (chunks.length === 0)
+            return;
+        const rows = chunks.map((content, i) => ({
+            document_id: doc.id,
+            chunk_index: i,
+            content,
+            embedding: embeddings[i] ? toVectorLiteral(embeddings[i]) : null,
+        }));
+        const { error } = await this.db.from("document_chunks").insert(rows);
+        if (error)
+            throw new Error(`indexDocument insert failed: ${error.message}`);
+    }
+    /** Rebuild the derived index for every document. The index is disposable. */
+    async reindexAll() {
+        const docs = await this.listDocuments({ limit: 1000 });
+        for (const doc of docs)
+            await this.indexDocument(doc);
+        await this.audit("reindex", null, { documents: docs.length });
+        return docs.length;
+    }
+    // -- search ---------------------------------------------------------------
+    /**
+     * Hybrid search: keyword (FTS + substring fallback in SQL) merged with
+     * vector similarity when embeddings are configured. Keyword-only is a
+     * fully supported mode — for a personal-scale memory it is often enough.
+     */
+    async search(query, opts = {}) {
+        const limit = opts.limit ?? 10;
+        const status = opts.status ?? "active";
+        const byDoc = new Map();
+        // Keyword path
+        const { data: kw, error: kwError } = await this.db.rpc("search_documents", {
+            p_query: query,
+            p_limit: limit * 3,
+            p_status: status,
+        });
+        if (kwError)
+            throw new Error(`search (keyword) failed: ${kwError.message}`);
+        const kwRows = (kw ?? []);
+        const maxRank = Math.max(...kwRows.map((r) => r.rank), 0);
+        for (const row of kwRows) {
+            byDoc.set(row.id, {
+                documentId: row.id,
+                title: row.title,
+                snippet: row.content_md.slice(0, 300),
+                score: maxRank > 0 ? row.rank / maxRank : 0.5,
+                via: ["keyword"],
+            });
+        }
+        // Vector path (only when an embedding provider is configured)
+        const queryVec = await embedText(this.cfg, query);
+        if (queryVec) {
+            const { data: vec, error: vecError } = await this.db.rpc("match_chunks", {
+                p_embedding: toVectorLiteral(queryVec),
+                p_limit: limit * 3,
+                p_status: status,
+            });
+            if (vecError)
+                throw new Error(`search (vector) failed: ${vecError.message}`);
+            const vecRows = (vec ?? []);
+            for (const row of vecRows) {
+                const existing = byDoc.get(row.document_id);
+                if (existing) {
+                    existing.via.push("vector");
+                    existing.score = Math.min(1, existing.score * 0.5 + row.similarity * 0.5);
+                    if (row.chunk.length > 0)
+                        existing.snippet = row.chunk.slice(0, 300);
+                }
+                else {
+                    byDoc.set(row.document_id, {
+                        documentId: row.document_id,
+                        title: row.title,
+                        snippet: row.chunk.slice(0, 300),
+                        score: row.similarity,
+                        via: ["vector"],
+                    });
+                }
+            }
+        }
+        return [...byDoc.values()]
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+    // -- audit ------------------------------------------------------------------
+    async audit(action, documentId, metadata) {
+        const { error } = await this.db.from("audit_log").insert({
+            actor: this.cfg.actor,
+            action,
+            document_id: documentId,
+            metadata,
+        });
+        if (error)
+            throw new Error(`audit failed: ${error.message}`);
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1 @@
-{
-  "name": "meminbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{"bin":{"meminbox":"./dist/cli.js","meminbox-mcp":"./dist/mcp/server.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.0","@supabase/supabase-js":"^2.45.0","pg":"^8.13.0","zod":"^4.6.7"},"description":"Shared memory for AI agents: Markdown documents in your own Supabase project are the source of truth; vector chunks are a rebuildable derived index. Agents connect over MCP, writes land in an inbox with provenance first.","devDependencies":{"@types/node":"^22.0.0","@types/pg":"^8.11.0","tsx":"^4.19.0","typescript":"^5.6.0"},"engines":{"node":">=20"},"files":["dist","supabase",".env.example"],"homepage":"https://github.com/daaquan/meminbox","keywords":["mcp","model-context-protocol","agent-memory","supabase","ai-agents"],"license":"MIT","name":"meminbox","repository":{"type":"git","url":"git+https://github.com/daaquan/meminbox.git"},"scripts":{"build":"tsc -p tsconfig.build.json","cli":"tsx src/cli.ts","mcp":"tsx src/mcp/server.ts","test":"tsx --test test/*.test.ts","typecheck":"tsc -p tsconfig.json --noEmit"},"type":"module","version":"0.2.1"}