mcp-simple-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-simple-memory contributors
+
+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,118 @@
+# mcp-simple-memory
+
+Persistent memory for Claude Code. **~500 lines, 1 file, zero external databases.**
+
+Claude Code forgets everything between sessions. This MCP server gives it a local SQLite memory that persists forever.
+
+## Why not claude-mem?
+
+| | claude-mem | mcp-simple-memory |
+|---|-----------|-------------------|
+| Codebase | ~20,000 lines | ~500 lines |
+| External DB | ChromaDB + Python | None (SQLite built-in) |
+| Windows | Broken (as of v10) | Works |
+| Setup | Complex | 1 command |
+| Search | Vector only | FTS5 + optional vector |
+
+## Quick Start
+
+```bash
+# In your project directory:
+npx mcp-simple-memory init
+```
+
+Restart Claude Code. Done. You now have `mem_save`, `mem_search`, `mem_get`, and `mem_list` tools.
+
+## Optional: Semantic Search
+
+Add a free [Gemini API key](https://aistudio.google.com/apikey) for meaning-based search:
+
+Edit `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "mcp-simple-memory": {
+      "command": "npx",
+      "args": ["-y", "mcp-simple-memory", "serve"],
+      "env": {
+        "GEMINI_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+Without a key, only FTS5 keyword search is used. With a key, the server automatically falls back to vector search when keyword search returns few results.
+
+## Tools
+
+### `mem_save`
+Save a memory.
+
+| Param | Required | Description |
+|-------|----------|-------------|
+| text | Yes | Content to save |
+| title | No | Short title (auto-generated) |
+| project | No | Project name (default: "default") |
+| type | No | memory, decision, error, session_summary |
+
+### `mem_search`
+Search memories by keyword or meaning.
+
+| Param | Required | Description |
+|-------|----------|-------------|
+| query | No | Search query (omit for recent) |
+| limit | No | Max results (default: 20) |
+| project | No | Filter by project |
+| mode | No | fts, vector, auto (default: auto) |
+
+### `mem_get`
+Fetch full details by ID.
+
+| Param | Required | Description |
+|-------|----------|-------------|
+| ids | Yes | Array of memory IDs |
+
+### `mem_list`
+List recent memories.
+
+| Param | Required | Description |
+|-------|----------|-------------|
+| limit | No | Max results (default: 20) |
+| project | No | Filter by project |
+
+## How It Works
+
+```
+mem_save("Fixed the auth bug by switching to OAuth2")
+    ↓
+SQLite (FTS5 index + optional Gemini embedding)
+    ↓
+mem_search("authentication problem")
+    → Finds it via FTS keyword match OR vector similarity
+```
+
+1. **FTS5**: SQLite full-text search. Fast, zero-config, keyword matching.
+2. **Gemini Embeddings** (optional): Converts text to 3072-dim vectors for semantic similarity. Free tier = 1500 requests/day.
+3. **Auto mode**: Tries FTS5 first. If < 3 results, falls back to vector search.
+
+## Data Storage
+
+All data stays local:
+- Database: `~/.mcp-simple-memory/memory.db`
+- Override: set `MCP_MEMORY_DIR` environment variable
+
+## Use with CLAUDE.md
+
+Add to your project's `CLAUDE.md` for automatic session memory:
+
+```markdown
+## Session Memory
+- On session start: use `mem_search` to find recent session summaries
+- During work: save important decisions with `mem_save` (type: "decision")
+- On session end: save a summary with `mem_save` (type: "session_summary")
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * CLI for mcp-simple-memory
+ *
+ * Usage:
+ *   npx mcp-simple-memory init   — Add to .mcp.json
+ *   npx mcp-simple-memory serve  — Start MCP server (used by Claude Code)
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * CLI for mcp-simple-memory
+ *
+ * Usage:
+ *   npx mcp-simple-memory init   — Add to .mcp.json
+ *   npx mcp-simple-memory serve  — Start MCP server (used by Claude Code)
+ */
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+const args = process.argv.slice(2);
+const command = args[0] || "serve";
+if (command === "init") {
+    init();
+}
+else if (command === "serve") {
+    // Import and run the server
+    await import("./index.js");
+}
+else if (command === "help" || command === "--help" || command === "-h") {
+    console.log(`
+mcp-simple-memory — Persistent memory for Claude Code
+
+Commands:
+  init    Add mcp-simple-memory to .mcp.json in current directory
+  serve   Start the MCP server (default, used by Claude Code)
+  help    Show this help
+
+Environment variables:
+  GEMINI_API_KEY     Enable semantic search (optional, free tier works)
+  MCP_MEMORY_DIR     Custom data directory (default: ~/.mcp-simple-memory)
+`);
+}
+else {
+    console.error(`Unknown command: ${command}. Run 'mcp-simple-memory help' for usage.`);
+    process.exit(1);
+}
+function init() {
+    const mcpPath = join(process.cwd(), ".mcp.json");
+    let config = {};
+    if (existsSync(mcpPath)) {
+        try {
+            config = JSON.parse(readFileSync(mcpPath, "utf-8"));
+        }
+        catch {
+            console.error("Error: existing .mcp.json is not valid JSON");
+            process.exit(1);
+        }
+    }
+    if (!config.mcpServers)
+        config.mcpServers = {};
+    if (config.mcpServers["mcp-simple-memory"]) {
+        console.log("mcp-simple-memory is already configured in .mcp.json");
+        return;
+    }
+    config.mcpServers["mcp-simple-memory"] = {
+        command: "npx",
+        args: ["-y", "mcp-simple-memory", "serve"],
+        env: {},
+    };
+    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
+    console.log(`Added mcp-simple-memory to ${mcpPath}`);
+    console.log("");
+    console.log("Next steps:");
+    console.log("  1. Restart Claude Code to load the new MCP server");
+    console.log("  2. (Optional) Add GEMINI_API_KEY to .mcp.json env for semantic search");
+    console.log("");
+    console.log("Example with semantic search:");
+    console.log('  "env": { "GEMINI_API_KEY": "your-key-here" }');
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * mcp-simple-memory — Persistent memory for Claude Code
+ *
+ * ~450 lines. SQLite (sql.js WASM, zero native deps).
+ * Optional Gemini semantic search. Works on Windows/Mac/Linux.
+ *
+ * Tools:
+ *   mem_save   — Save a memory
+ *   mem_search — Search (keyword + optional vector)
+ *   mem_get    — Fetch by IDs
+ *   mem_list   — Recent memories
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+/**
+ * mcp-simple-memory — Persistent memory for Claude Code
+ *
+ * ~450 lines. SQLite (sql.js WASM, zero native deps).
+ * Optional Gemini semantic search. Works on Windows/Mac/Linux.
+ *
+ * Tools:
+ *   mem_save   — Save a memory
+ *   mem_search — Search (keyword + optional vector)
+ *   mem_get    — Fetch by IDs
+ *   mem_list   — Recent memories
+ */
+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 initSqlJs from "sql.js";
+import { join } from "path";
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+// ─── Config ────────────────────────────────────────────────────
+const DATA_DIR = process.env.MCP_MEMORY_DIR || join(homedir(), ".mcp-simple-memory");
+const DB_PATH = join(DATA_DIR, "memory.db");
+const GEMINI_API_KEY = process.env.GEMINI_API_KEY || "";
+const GEMINI_MODEL = "gemini-embedding-001";
+const EMBEDDING_DIMS = 3072;
+if (!existsSync(DATA_DIR)) {
+    mkdirSync(DATA_DIR, { recursive: true });
+}
+// ─── Database ──────────────────────────────────────────────────
+let db;
+async function initDb() {
+    const SQL = await initSqlJs();
+    if (existsSync(DB_PATH)) {
+        db = new SQL.Database(readFileSync(DB_PATH));
+    }
+    else {
+        db = new SQL.Database();
+    }
+    db.run(`
+    CREATE TABLE IF NOT EXISTS memories (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT,
+      content TEXT NOT NULL,
+      type TEXT DEFAULT 'memory',
+      project TEXT DEFAULT 'default',
+      created_at INTEGER NOT NULL,
+      created_iso TEXT NOT NULL
+    );
+  `);
+    db.run(`
+    CREATE TABLE IF NOT EXISTS embeddings (
+      memory_id INTEGER PRIMARY KEY,
+      vector BLOB NOT NULL
+    );
+  `);
+    db.run(`CREATE INDEX IF NOT EXISTS idx_mem_project ON memories(project);`);
+    db.run(`CREATE INDEX IF NOT EXISTS idx_mem_created ON memories(created_at);`);
+    db.run(`CREATE INDEX IF NOT EXISTS idx_mem_type ON memories(type);`);
+    persist();
+}
+function persist() {
+    writeFileSync(DB_PATH, Buffer.from(db.export()));
+}
+// ─── Query helper ──────────────────────────────────────────────
+function queryAll(sql, params = []) {
+    const stmt = db.prepare(sql);
+    if (params.length)
+        stmt.bind(params);
+    const rows = [];
+    while (stmt.step())
+        rows.push(stmt.getAsObject());
+    stmt.free();
+    return rows;
+}
+function getByIds(ids) {
+    if (!ids.length)
+        return [];
+    return queryAll(`SELECT * FROM memories WHERE id IN (${ids.map(() => "?").join(",")})`, ids);
+}
+// ─── Gemini Embeddings ─────────────────────────────────────────
+async function getEmbedding(text) {
+    if (!GEMINI_API_KEY)
+        return null;
+    try {
+        const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${GEMINI_MODEL}:embedContent?key=${GEMINI_API_KEY}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                model: `models/${GEMINI_MODEL}`,
+                content: { parts: [{ text }] },
+            }),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return new Float32Array(data.embedding.values);
+    }
+    catch {
+        return null;
+    }
+}
+function cosine(a, b) {
+    let dot = 0, nA = 0, nB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        nA += a[i] * a[i];
+        nB += b[i] * b[i];
+    }
+    return dot / (Math.sqrt(nA) * Math.sqrt(nB));
+}
+async function vectorSearch(query, limit, project) {
+    const qVec = await getEmbedding(query);
+    if (!qVec)
+        return [];
+    const sql = project
+        ? `SELECT e.memory_id, e.vector FROM embeddings e JOIN memories m ON m.id = e.memory_id WHERE m.project = ?`
+        : `SELECT memory_id, vector FROM embeddings`;
+    const rows = queryAll(sql, project ? [project] : []);
+    const scored = rows.map((r) => {
+        const buf = r.vector instanceof Uint8Array ? r.vector : new Uint8Array(r.vector);
+        const vec = new Float32Array(buf.buffer, buf.byteOffset, EMBEDDING_DIMS);
+        return { id: r.memory_id, score: cosine(qVec, vec) };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit);
+}
+// ─── Response helpers ──────────────────────────────────────────
+function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+function err(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+function formatRows(rows, header) {
+    if (!rows.length)
+        return ok(`${header}\n\n(no results)`);
+    const lines = rows.map((r) => {
+        const preview = (r.content || "").substring(0, 150).replace(/\n/g, " ");
+        return `#${r.id} | ${r.type} | ${r.project} | ${r.created_iso}\n  ${r.title || "(no title)"}\n  ${preview}`;
+    });
+    return ok(`# ${header} (${rows.length})\n\n${lines.join("\n\n")}`);
+}
+// ─── Tool Handlers ─────────────────────────────────────────────
+async function handleSave(args) {
+    const content = args.text || args.content;
+    if (!content)
+        return err("text is required");
+    const now = Date.now();
+    const title = args.title || content.substring(0, 80);
+    const project = args.project || "default";
+    const type = args.type || "memory";
+    db.run(`INSERT INTO memories (title, content, type, project, created_at, created_iso) VALUES (?, ?, ?, ?, ?, ?)`, [title, content, type, project, now, new Date(now).toISOString()]);
+    const id = queryAll(`SELECT last_insert_rowid() as id`)[0]?.id ?? 0;
+    persist();
+    // Background embedding
+    if (GEMINI_API_KEY) {
+        getEmbedding(`${title}\n${content}`).then((vec) => {
+            if (vec) {
+                db.run(`INSERT OR REPLACE INTO embeddings (memory_id, vector) VALUES (?, ?)`, [
+                    id,
+                    vec.buffer,
+                ]);
+                persist();
+            }
+        });
+    }
+    return ok(`Saved memory #${id} (project: ${project})`);
+}
+async function handleSearch(args) {
+    const query = args.query;
+    const limit = args.limit || 20;
+    const project = args.project;
+    const mode = args.mode || "auto";
+    // No query → return recent
+    if (!query) {
+        const sql = project
+            ? `SELECT * FROM memories WHERE project = ? ORDER BY created_at DESC LIMIT ?`
+            : `SELECT * FROM memories ORDER BY created_at DESC LIMIT ?`;
+        return formatRows(queryAll(sql, project ? [project, limit] : [limit]), "Recent memories");
+    }
+    let kwResults = [];
+    let vecResults = [];
+    // Keyword search (LIKE)
+    if (mode === "fts" || mode === "keyword" || mode === "auto") {
+        const words = query.split(/\s+/).filter((w) => w.length > 0);
+        if (words.length) {
+            const conds = words.map(() => `(title LIKE ? OR content LIKE ?)`).join(" OR ");
+            const params = [];
+            for (const w of words) {
+                params.push(`%${w}%`, `%${w}%`);
+            }
+            let sql = `SELECT * FROM memories WHERE (${conds})`;
+            if (project) {
+                sql += ` AND project = ?`;
+                params.push(project);
+            }
+            sql += ` ORDER BY created_at DESC LIMIT ?`;
+            params.push(limit);
+            kwResults = queryAll(sql, params);
+        }
+    }
+    // Vector search (if keyword found few results)
+    if ((mode === "vector" || (mode === "auto" && kwResults.length < 3)) && GEMINI_API_KEY) {
+        vecResults = await vectorSearch(query, limit, project);
+    }
+    // Merge
+    if (vecResults.length && kwResults.length) {
+        const kwIds = new Set(kwResults.map((r) => r.id));
+        const extra = vecResults.filter((r) => !kwIds.has(r.id)).map((r) => r.id);
+        if (extra.length)
+            kwResults = [...kwResults, ...getByIds(extra)];
+        return formatRows(kwResults.slice(0, limit), `Search: "${query}" (Keyword+Vector)`);
+    }
+    if (vecResults.length) {
+        return formatRows(getByIds(vecResults.map((r) => r.id)).slice(0, limit), `Search: "${query}" (Vector)`);
+    }
+    return formatRows(kwResults.slice(0, limit), `Search: "${query}" (Keyword)`);
+}
+async function handleGet(args) {
+    const ids = args.ids;
+    if (!ids?.length)
+        return err("ids array is required");
+    return formatRows(getByIds(ids), `Fetched ${ids.length} memories`);
+}
+async function handleList(args) {
+    const limit = args.limit || 20;
+    const project = args.project;
+    const sql = project
+        ? `SELECT * FROM memories WHERE project = ? ORDER BY created_at DESC LIMIT ?`
+        : `SELECT * FROM memories ORDER BY created_at DESC LIMIT ?`;
+    return formatRows(queryAll(sql, project ? [project, limit] : [limit]), "Memories");
+}
+// ─── MCP Server ────────────────────────────────────────────────
+const server = new Server({ name: "mcp-simple-memory", version: "0.1.0" }, { capabilities: { tools: {} } });
+const tools = [
+    {
+        name: "mem_save",
+        description: "Save a memory. Params: text (required), title, project, type (memory/decision/error/session_summary)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                text: { type: "string", description: "Content to save" },
+                title: { type: "string", description: "Short title (auto-generated if omitted)" },
+                project: { type: "string", description: "Project name (default: 'default')" },
+                type: { type: "string", description: "Type: memory, decision, error, session_summary" },
+            },
+            required: ["text"],
+        },
+    },
+    {
+        name: "mem_search",
+        description: "Search memories by keyword or meaning. Params: query, limit, project, mode (keyword/vector/auto)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query (omit for recent)" },
+                limit: { type: "number", description: "Max results (default: 20)" },
+                project: { type: "string", description: "Filter by project" },
+                mode: { type: "string", description: "keyword, vector, or auto (default: auto)" },
+            },
+        },
+    },
+    {
+        name: "mem_get",
+        description: "Fetch full details for specific memory IDs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ids: { type: "array", items: { type: "number" }, description: "Memory IDs to fetch" },
+            },
+            required: ["ids"],
+        },
+    },
+    {
+        name: "mem_list",
+        description: "List recent memories. Params: limit, project",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Max results (default: 20)" },
+                project: { type: "string", description: "Filter by project" },
+            },
+        },
+    },
+];
+const handlers = {
+    mem_save: handleSave,
+    mem_search: handleSearch,
+    mem_get: handleGet,
+    mem_list: handleList,
+};
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const handler = handlers[request.params.name];
+    if (!handler)
+        throw new Error(`Unknown tool: ${request.params.name}`);
+    try {
+        return await handler(request.params.arguments || {});
+    }
+    catch (error) {
+        return err(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+});
+// ─── Start ─────────────────────────────────────────────────────
+console.log = console.error; // MCP uses stdout for JSON-RPC
+async function main() {
+    await initDb();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[mcp-simple-memory] DB: ${DB_PATH} | Embeddings: ${GEMINI_API_KEY ? "ON" : "OFF"}`);
+}
+main().catch((e) => {
+    console.error(`[mcp-simple-memory] Fatal: ${e}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "mcp-simple-memory",
+  "version": "0.1.0",
+  "description": "Simple persistent memory for Claude Code. ~500 lines, SQLite, optional semantic search. Zero native deps.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-simple-memory": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "memory",
+    "sqlite",
+    "persistent-memory",
+    "model-context-protocol",
+    "ai-tools"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "sql.js": "^1.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@types/sql.js": "^1.4.9",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ohsim713-cmd/mcp-simple-memory"
+  }
+}