apex-memory 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 EIGA
+
+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,171 @@
+# apex-memory
+
+[![CI](https://github.com/JJerryChoi/apex-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/JJerryChoi/apex-memory/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/apex-memory.svg)](https://www.npmjs.com/package/apex-memory)
+[![npm downloads](https://img.shields.io/npm/dm/apex-memory.svg)](https://www.npmjs.com/package/apex-memory)
+
+**Persistent memory for AI coding agents.**
+
+Give your AI coding agent memory that survives across sessions. apex-memory is an [MCP](https://modelcontextprotocol.io) server that lets agents save decisions, patterns, bugs, and context — then recall them exactly when needed.
+
+- **One install, works everywhere** — MCP-native, works with Claude Code, Cursor, Windsurf, and any MCP-compatible editor
+- **Zero infrastructure** — local SQLite database, no servers, no accounts
+- **Built for coding agents** — categories like `decision`, `architecture`, `bug`, `pattern` designed for real development workflows
+- **Full-text search** — find any memory instantly with FTS5-powered search
+
+## Quick Start
+
+### Claude Code
+
+```bash
+claude mcp add apex-memory -- npx apex-memory
+```
+
+That's it. Your agent now has persistent memory.
+
+### Cursor
+
+Add to your MCP settings (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "apex-memory": {
+      "command": "npx",
+      "args": ["apex-memory"]
+    }
+  }
+}
+```
+
+See the [Cursor setup guide](docs/guides/cursor.md) for full details and troubleshooting.
+
+### Windsurf
+
+Open `~/.codeium/windsurf/mcp_config.json` (via `Cmd+Shift+P` → "Windsurf: Open MCP Config") and add:
+
+```json
+{
+  "mcpServers": {
+    "apex-memory": {
+      "command": "npx",
+      "args": ["apex-memory"]
+    }
+  }
+}
+```
+
+See the [Windsurf setup guide](docs/guides/windsurf.md) for full details and troubleshooting.
+
+### Other MCP Clients
+
+apex-memory works with any MCP-compatible client. Point it at:
+
+```bash
+npx apex-memory
+```
+
+The server communicates over stdio using the standard MCP protocol. See the [generic MCP setup guide](docs/guides/generic-mcp.md) for examples with VS Code, Continue.dev, and custom clients.
+
+## Tools
+
+apex-memory gives your agent 9 tools:
+
+| Tool | Description |
+|------|-------------|
+| `save_memory` | Save knowledge, decisions, patterns, or context with categories, tags, and importance scoring (1–5) |
+| `search_memories` | Full-text search across all memories (supports AND, OR, NOT, phrases) |
+| `recall` | Retrieve recent memories filtered by project, category, or tags |
+| `delete_memory` | Remove a specific memory by ID |
+| `decay_memories` | Archive old low-importance memories that were never accessed — keeps the store clean |
+| `start_session` | Begin a coding session tied to a project |
+| `end_session` | End a session with a summary of what was accomplished |
+| `list_sessions` | View past coding sessions |
+| `memory_stats` | Get statistics about stored memories and sessions |
+
+## How It Works
+
+When your agent encounters something worth remembering — an architectural decision, a tricky bug fix, a user preference — it calls `save_memory`:
+
+```
+save_memory({
+  content: "User prefers functional components over class components in React",
+  category: "preference",
+  tags: ["react", "components"],
+  project: "frontend-app"
+})
+```
+
+Next session, the agent recalls context before starting work:
+
+```
+recall({ project: "frontend-app" })
+```
+
+Or searches for something specific:
+
+```
+search_memories({ query: "authentication AND JWT" })
+```
+
+### Categories
+
+Organize memories by what they represent:
+
+| Category | Use for |
+|----------|---------|
+| `decision` | Architectural and design decisions |
+| `pattern` | Code patterns and conventions |
+| `bug` | Bugs encountered and their fixes |
+| `architecture` | System design and structure |
+| `preference` | User and team preferences |
+| `learning` | Lessons learned |
+| `context` | Project context and background |
+| `general` | Everything else |
+
+### Sessions
+
+Track coding sessions to group related memories:
+
+```
+start_session({ project: "api-server" })
+// ... agent works, saves memories with the session_id ...
+end_session({ session_id: "...", summary: "Refactored auth middleware to use JWT" })
+```
+
+## Storage
+
+All data is stored locally in `~/.apex-memory/memory.db` — a SQLite database with WAL mode and FTS5 full-text search. No data leaves your machine.
+
+## Pricing
+
+| Tier | What you get | Price |
+|------|-------------|-------|
+| **Free** | Local storage, unlimited sessions, single machine | $0 |
+| **Pro** | Cloud sync across machines, search API, up to 1GB | $9/workspace/month |
+| **Team** | Shared multi-agent memory, analytics, unlimited storage | $29/workspace/month |
+
+The free tier is fully functional. Pro and Team tiers are coming soon.
+
+## Why apex-memory?
+
+| | apex-memory | Mem0 | Letta | OneContext |
+|---|---|---|---|---|
+| **Built for coding agents** | Yes | General purpose | General purpose | General purpose |
+| **MCP-native** | Yes | No | No | No |
+| **Zero infrastructure** | Yes (SQLite) | Requires server | Requires server | Cloud-only |
+| **Install time** | 30 seconds | Minutes | Minutes | Minutes |
+| **Works with Claude Code** | Yes | Manual integration | Manual integration | No |
+| **Session tracking** | Built-in | No | No | No |
+| **Full-text search** | FTS5 | Vector search | Vector search | Vector search |
+| **Open source** | MIT | Partial | Yes | No |
+
+apex-memory is purpose-built for the coding agent workflow. It's not a general-purpose memory layer — it's the memory system your AI coding agent should have had from day one.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[MIT](LICENSE)

package/build/database.d.ts

@@ -0,0 +1,39 @@
+import Database from "better-sqlite3";
+export interface Memory {
+    id: string;
+    content: string;
+    category: string;
+    tags: string;
+    project: string;
+    session_id: string | null;
+    importance: number;
+    access_count: number;
+    last_accessed_at: string | null;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+export interface Session {
+    id: string;
+    project: string;
+    summary: string | null;
+    started_at: string;
+    ended_at: string | null;
+}
+export declare function createDatabase(dbPath?: string): Database.Database;
+export declare function saveMemory(db: Database.Database, content: string, category: string, tags: string[], project: string, sessionId?: string, importance?: number): Memory;
+export declare function searchMemories(db: Database.Database, query: string, project?: string, limit?: number): Memory[];
+export declare function recallMemories(db: Database.Database, project?: string, category?: string, tags?: string[], limit?: number): Memory[];
+export declare function deleteMemory(db: Database.Database, id: string): boolean;
+export declare function decayMemories(db: Database.Database, dayThreshold?: number, maxImportance?: number): number;
+export declare function startSession(db: Database.Database, project: string): Session;
+export declare function endSession(db: Database.Database, sessionId: string, summary: string): Session | null;
+export declare function listSessions(db: Database.Database, project?: string, limit?: number): Session[];
+export declare function getStats(db: Database.Database): {
+    memories: number;
+    sessions: number;
+    projects: string[];
+};
+export declare function getSyncState(db: Database.Database, key: string): string | null;
+export declare function setSyncState(db: Database.Database, key: string, value: string): void;
+//# sourceMappingURL=database.d.ts.map

package/build/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAMtC,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAqDD,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CA+DjE;AAYD,wBAAgB,UAAU,CACxB,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAClB,UAAU,GAAE,MAAU,GACrB,MAAM,CAwBR;AAED,wBAAgB,cAAc,CAC5B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,GAAE,MAAW,GACjB,MAAM,EAAE,CAqCV;AAED,wBAAgB,cAAc,CAC5B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,OAAO,CAAC,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,KAAK,GAAE,MAAW,GACjB,MAAM,EAAE,CA6BV;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAMvE;AAED,wBAAgB,aAAa,CAC3B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,YAAY,GAAE,MAAW,EACzB,aAAa,GAAE,MAAU,GACxB,MAAM,CAYR;AAED,wBAAgB,YAAY,CAC1B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAST;AAED,wBAAgB,UAAU,CACxB,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,GAAG,IAAI,CAUhB;AAED,wBAAgB,YAAY,CAC1B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,GAAE,MAAW,GACjB,OAAO,EAAE,CASX;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAK1G;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9E;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAEpF"}

package/build/database.js

@@ -0,0 +1,257 @@
+import Database from "better-sqlite3";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+function getDbPath() {
+    const dir = join(homedir(), ".apex-memory");
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    return join(dir, "memory.db");
+}
+function runMigrations(db) {
+    const columns = db.pragma("table_info(memories)").map((c) => c.name);
+    if (!columns.includes("importance")) {
+        db.exec(`ALTER TABLE memories ADD COLUMN importance INTEGER NOT NULL DEFAULT 3`);
+    }
+    if (!columns.includes("access_count")) {
+        db.exec(`ALTER TABLE memories ADD COLUMN access_count INTEGER NOT NULL DEFAULT 0`);
+    }
+    if (!columns.includes("last_accessed_at")) {
+        db.exec(`ALTER TABLE memories ADD COLUMN last_accessed_at TEXT`);
+    }
+    if (!columns.includes("deleted_at")) {
+        db.exec(`ALTER TABLE memories ADD COLUMN deleted_at TEXT`);
+    }
+    if (!columns.includes("updated_at")) {
+        db.exec(`ALTER TABLE memories ADD COLUMN updated_at TEXT`);
+        db.exec(`UPDATE memories SET updated_at = created_at WHERE updated_at IS NULL`);
+    }
+    // Ensure sync_state table exists (idempotent)
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS sync_state (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    )
+  `);
+    // Update memories_au trigger to exclude soft-deleted rows from FTS
+    db.exec(`
+    DROP TRIGGER IF EXISTS memories_au;
+    CREATE TRIGGER memories_au AFTER UPDATE ON memories BEGIN
+      INSERT INTO memories_fts(memories_fts, rowid, content, category, tags, project)
+      VALUES('delete', old.rowid, old.content, old.category, old.tags, old.project);
+      INSERT INTO memories_fts(rowid, content, category, tags, project)
+      SELECT new.rowid, new.content, new.category, new.tags, new.project
+      WHERE new.deleted_at IS NULL;
+    END
+  `);
+}
+export function createDatabase(dbPath) {
+    const path = dbPath ?? getDbPath();
+    const db = new Database(path);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS memories (
+      id TEXT PRIMARY KEY,
+      content TEXT NOT NULL,
+      category TEXT NOT NULL DEFAULT 'general',
+      tags TEXT NOT NULL DEFAULT '',
+      project TEXT NOT NULL DEFAULT '',
+      session_id TEXT,
+      importance INTEGER NOT NULL DEFAULT 3,
+      access_count INTEGER NOT NULL DEFAULT 0,
+      last_accessed_at TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT,
+      deleted_at TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      project TEXT NOT NULL DEFAULT '',
+      summary TEXT,
+      started_at TEXT NOT NULL,
+      ended_at TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS sync_state (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+      content, category, tags, project,
+      content=memories, content_rowid=rowid
+    );
+
+    CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+      INSERT INTO memories_fts(rowid, content, category, tags, project)
+      VALUES (new.rowid, new.content, new.category, new.tags, new.project);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+      INSERT INTO memories_fts(memories_fts, rowid, content, category, tags, project)
+      VALUES('delete', old.rowid, old.content, old.category, old.tags, old.project);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+      INSERT INTO memories_fts(memories_fts, rowid, content, category, tags, project)
+      VALUES('delete', old.rowid, old.content, old.category, old.tags, old.project);
+      INSERT INTO memories_fts(rowid, content, category, tags, project)
+      SELECT new.rowid, new.content, new.category, new.tags, new.project
+      WHERE new.deleted_at IS NULL;
+    END;
+  `);
+    runMigrations(db);
+    return db;
+}
+function touchMemories(db, ids) {
+    if (ids.length === 0)
+        return;
+    const now = new Date().toISOString();
+    const placeholders = ids.map(() => "?").join(",");
+    db.prepare(`UPDATE memories SET access_count = access_count + 1, last_accessed_at = ?, updated_at = ?
+     WHERE id IN (${placeholders})`).run(now, now, ...ids);
+}
+export function saveMemory(db, content, category, tags, project, sessionId, importance = 3) {
+    const id = randomUUID();
+    const now = new Date().toISOString();
+    const tagsStr = tags.join(",");
+    db.prepare(`INSERT INTO memories (id, content, category, tags, project, session_id, importance, access_count, last_accessed_at, created_at, updated_at, deleted_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, 0, NULL, ?, ?, NULL)`).run(id, content, category, tagsStr, project, sessionId ?? null, importance, now, now);
+    return {
+        id,
+        content,
+        category,
+        tags: tagsStr,
+        project,
+        session_id: sessionId ?? null,
+        importance,
+        access_count: 0,
+        last_accessed_at: null,
+        created_at: now,
+        updated_at: now,
+        deleted_at: null,
+    };
+}
+export function searchMemories(db, query, project, limit = 20) {
+    let rows;
+    if (project) {
+        rows = db
+            .prepare(`SELECT m.* FROM memories m
+         JOIN memories_fts f ON m.rowid = f.rowid
+         WHERE memories_fts MATCH ? AND m.project = ? AND m.deleted_at IS NULL
+         ORDER BY rank
+         LIMIT ?`)
+            .all(query, project, limit);
+    }
+    else {
+        rows = db
+            .prepare(`SELECT m.* FROM memories m
+         JOIN memories_fts f ON m.rowid = f.rowid
+         WHERE memories_fts MATCH ? AND m.deleted_at IS NULL
+         ORDER BY rank
+         LIMIT ?`)
+            .all(query, limit);
+    }
+    // Deduplicate — FTS5 join can return duplicate rows
+    const seen = new Set();
+    const results = rows.filter((m) => {
+        if (seen.has(m.id))
+            return false;
+        seen.add(m.id);
+        return true;
+    });
+    const searchNow = new Date().toISOString();
+    touchMemories(db, results.map((m) => m.id));
+    for (const m of results) {
+        m.access_count += 1;
+        m.last_accessed_at = searchNow;
+    }
+    return results;
+}
+export function recallMemories(db, project, category, tags, limit = 20) {
+    let sql = `SELECT * FROM memories WHERE deleted_at IS NULL`;
+    const params = [];
+    if (project) {
+        sql += ` AND project = ?`;
+        params.push(project);
+    }
+    if (category) {
+        sql += ` AND category = ?`;
+        params.push(category);
+    }
+    if (tags && tags.length > 0) {
+        for (const tag of tags) {
+            sql += ` AND tags LIKE ?`;
+            params.push(`%${tag}%`);
+        }
+    }
+    sql += ` ORDER BY created_at DESC LIMIT ?`;
+    params.push(limit);
+    const results = db.prepare(sql).all(...params);
+    const recallNow = new Date().toISOString();
+    touchMemories(db, results.map((m) => m.id));
+    for (const m of results) {
+        m.access_count += 1;
+        m.last_accessed_at = recallNow;
+    }
+    return results;
+}
+export function deleteMemory(db, id) {
+    const now = new Date().toISOString();
+    const result = db
+        .prepare(`UPDATE memories SET deleted_at = ?, updated_at = ? WHERE id = ? AND deleted_at IS NULL`)
+        .run(now, now, id);
+    return result.changes > 0;
+}
+export function decayMemories(db, dayThreshold = 30, maxImportance = 2) {
+    const now = new Date().toISOString();
+    const result = db
+        .prepare(`UPDATE memories SET deleted_at = ?, updated_at = ?
+       WHERE importance <= ?
+         AND access_count = 0
+         AND deleted_at IS NULL
+         AND created_at < datetime('now', ? || ' days')`)
+        .run(now, now, maxImportance, `-${dayThreshold}`);
+    return result.changes;
+}
+export function startSession(db, project) {
+    const id = randomUUID();
+    const now = new Date().toISOString();
+    db.prepare(`INSERT INTO sessions (id, project, started_at) VALUES (?, ?, ?)`).run(id, project, now);
+    return { id, project, summary: null, started_at: now, ended_at: null };
+}
+export function endSession(db, sessionId, summary) {
+    const now = new Date().toISOString();
+    const result = db.prepare(`UPDATE sessions SET summary = ?, ended_at = ? WHERE id = ?`).run(summary, now, sessionId);
+    if (result.changes === 0)
+        return null;
+    return db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(sessionId);
+}
+export function listSessions(db, project, limit = 20) {
+    if (project) {
+        return db
+            .prepare(`SELECT * FROM sessions WHERE project = ? ORDER BY started_at DESC LIMIT ?`)
+            .all(project, limit);
+    }
+    return db
+        .prepare(`SELECT * FROM sessions ORDER BY started_at DESC LIMIT ?`)
+        .all(limit);
+}
+export function getStats(db) {
+    const memoriesCount = db.prepare(`SELECT COUNT(*) as count FROM memories WHERE deleted_at IS NULL`).get().count;
+    const sessionsCount = db.prepare(`SELECT COUNT(*) as count FROM sessions`).get().count;
+    const projects = db.prepare(`SELECT DISTINCT project FROM memories WHERE project != '' AND deleted_at IS NULL ORDER BY project`).all().map(r => r.project);
+    return { memories: memoriesCount, sessions: sessionsCount, projects };
+}
+export function getSyncState(db, key) {
+    const row = db.prepare(`SELECT value FROM sync_state WHERE key = ?`).get(key);
+    return row?.value ?? null;
+}
+export function setSyncState(db, key, value) {
+    db.prepare(`INSERT INTO sync_state (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(key, value);
+}
+//# sourceMappingURL=database.js.map

package/build/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"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"}

package/build/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/build/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createDatabase } from "./database.js";
+import { registerTools } from "./tools.js";
+const server = new McpServer({
+    name: "apex-memory",
+    version: "0.1.0",
+});
+const db = createDatabase();
+registerTools(server, db);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("apex-memory v0.1.0 running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,MAAM,EAAE,GAAG,cAAc,EAAE,CAAC;AAC5B,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAE1B,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;AACvD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/build/tools.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type Database from "better-sqlite3";
+export declare function registerTools(server: McpServer, db: Database.Database): void;
+//# sourceMappingURL=tools.d.ts.map

package/build/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAa3C,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CA4P5E"}

package/build/tools.js

@@ -0,0 +1,193 @@
+import { z } from "zod";
+import { saveMemory, searchMemories, recallMemories, deleteMemory, decayMemories, startSession, endSession, listSessions, getStats, } from "./database.js";
+export function registerTools(server, db) {
+    server.tool("save_memory", "Save a piece of knowledge, decision, pattern, or context for future recall. Use categories like: decision, pattern, bug, architecture, preference, learning, context.", {
+        content: z.string().describe("The memory content to save"),
+        category: z
+            .string()
+            .default("general")
+            .describe("Category: decision, pattern, bug, architecture, preference, learning, context, general"),
+        tags: z
+            .array(z.string())
+            .default([])
+            .describe("Tags for filtering and organization"),
+        project: z
+            .string()
+            .default("")
+            .describe("Project name this memory belongs to"),
+        session_id: z
+            .string()
+            .optional()
+            .describe("Session ID if this memory is part of an active session"),
+        importance: z
+            .number()
+            .int()
+            .min(1)
+            .max(5)
+            .default(3)
+            .describe("Importance score 1-5 (1=low/ephemeral, 3=default, 5=critical decision)"),
+    }, async ({ content, category, tags, project, session_id, importance }) => {
+        const memory = saveMemory(db, content, category, tags, project, session_id, importance);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Saved memory ${memory.id}\nCategory: ${memory.category}\nProject: ${memory.project || "(global)"}\nTags: ${memory.tags || "(none)"}\nImportance: ${memory.importance}/5`,
+                },
+            ],
+        };
+    });
+    server.tool("search_memories", "Full-text search across all stored memories. Returns the most relevant matches.", {
+        query: z.string().describe("Search query (supports FTS5 syntax: AND, OR, NOT, phrases)"),
+        project: z
+            .string()
+            .optional()
+            .describe("Filter to a specific project"),
+        limit: z.number().default(20).describe("Max results to return"),
+    }, async ({ query, project, limit }) => {
+        const memories = searchMemories(db, query, project, limit);
+        if (memories.length === 0) {
+            return {
+                content: [{ type: "text", text: "No memories found matching your query." }],
+            };
+        }
+        const formatted = memories
+            .map((m) => `[${m.id}] (${m.category}) [importance:${m.importance}] ${m.project ? `[${m.project}]` : ""} ${m.created_at}\n${m.content}${m.tags ? `\nTags: ${m.tags}` : ""}`)
+            .join("\n---\n");
+        return {
+            content: [{ type: "text", text: `Found ${memories.length} memories:\n\n${formatted}` }],
+        };
+    });
+    server.tool("recall", "Retrieve recent memories filtered by project, category, or tags. Use at the start of a session to restore context.", {
+        project: z
+            .string()
+            .optional()
+            .describe("Filter to a specific project"),
+        category: z
+            .string()
+            .optional()
+            .describe("Filter by category"),
+        tags: z
+            .array(z.string())
+            .optional()
+            .describe("Filter by tags (all must match)"),
+        limit: z.number().default(20).describe("Max results to return"),
+    }, async ({ project, category, tags, limit }) => {
+        const memories = recallMemories(db, project, category, tags, limit);
+        if (memories.length === 0) {
+            return {
+                content: [{ type: "text", text: "No memories found with the given filters." }],
+            };
+        }
+        const formatted = memories
+            .map((m) => `[${m.id}] (${m.category}) [importance:${m.importance}] ${m.project ? `[${m.project}]` : ""} ${m.created_at}\n${m.content}${m.tags ? `\nTags: ${m.tags}` : ""}`)
+            .join("\n---\n");
+        return {
+            content: [{ type: "text", text: `Recalled ${memories.length} memories:\n\n${formatted}` }],
+        };
+    });
+    server.tool("delete_memory", "Delete a specific memory by ID.", {
+        id: z.string().describe("The memory ID to delete"),
+    }, async ({ id }) => {
+        const deleted = deleteMemory(db, id);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: deleted ? `Deleted memory ${id}` : `Memory ${id} not found`,
+                },
+            ],
+        };
+    });
+    server.tool("decay_memories", "Archive (delete) low-importance memories that have never been accessed and are older than a threshold. Keeps the memory store clean by removing stale, low-value context.", {
+        day_threshold: z
+            .number()
+            .int()
+            .min(1)
+            .default(30)
+            .describe("Delete memories older than this many days (default 30)"),
+        max_importance: z
+            .number()
+            .int()
+            .min(1)
+            .max(4)
+            .default(2)
+            .describe("Only delete memories with importance <= this value (default 2; never deletes importance 5)"),
+    }, async ({ day_threshold, max_importance }) => {
+        const deleted = decayMemories(db, day_threshold, max_importance);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: deleted === 0
+                        ? `No memories decayed. No stale low-importance memories found older than ${day_threshold} days.`
+                        : `Decayed ${deleted} memories (importance ≤ ${max_importance}, never accessed, older than ${day_threshold} days).`,
+                },
+            ],
+        };
+    });
+    server.tool("start_session", "Start a new coding session. Returns a session ID to associate memories with this session.", {
+        project: z.string().describe("Project name for this session"),
+    }, async ({ project }) => {
+        const session = startSession(db, project);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Started session ${session.id}\nProject: ${session.project}\nStarted: ${session.started_at}`,
+                },
+            ],
+        };
+    });
+    server.tool("end_session", "End a coding session with a summary of what was accomplished.", {
+        session_id: z.string().describe("The session ID to end"),
+        summary: z.string().describe("Summary of what was accomplished in this session"),
+    }, async ({ session_id, summary }) => {
+        const session = endSession(db, session_id, summary);
+        if (!session) {
+            return {
+                content: [{ type: "text", text: `Session ${session_id} not found` }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Ended session ${session.id}\nProject: ${session.project}\nDuration: ${session.started_at} → ${session.ended_at}\nSummary: ${session.summary}`,
+                },
+            ],
+        };
+    });
+    server.tool("list_sessions", "List past coding sessions, optionally filtered by project.", {
+        project: z
+            .string()
+            .optional()
+            .describe("Filter to a specific project"),
+        limit: z.number().default(20).describe("Max results to return"),
+    }, async ({ project, limit }) => {
+        const sessions = listSessions(db, project, limit);
+        if (sessions.length === 0) {
+            return {
+                content: [{ type: "text", text: "No sessions found." }],
+            };
+        }
+        const formatted = sessions
+            .map((s) => `[${s.id}] ${s.project} | ${s.started_at} → ${s.ended_at ?? "active"}${s.summary ? `\n  ${s.summary}` : ""}`)
+            .join("\n");
+        return {
+            content: [{ type: "text", text: `Sessions:\n\n${formatted}` }],
+        };
+    });
+    server.tool("memory_stats", "Get statistics about stored memories and sessions.", {}, async () => {
+        const stats = getStats(db);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Memories: ${stats.memories}\nSessions: ${stats.sessions}\nProjects: ${stats.projects.length > 0 ? stats.projects.join(", ") : "(none)"}`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=tools.js.map

package/build/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "apex-memory",
+  "version": "0.2.0",
+  "description": "Persistent memory MCP server for AI coding agents",
+  "type": "module",
+  "bin": {
+    "apex-memory": "build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "files": [
+    "build",
+    "!build/__tests__"
+  ],
+  "keywords": [
+    "mcp",
+    "memory",
+    "ai",
+    "coding-agents",
+    "persistent-context"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JJerryChoi/apex-memory.git"
+  },
+  "homepage": "https://github.com/JJerryChoi/apex-memory#readme",
+  "bugs": {
+    "url": "https://github.com/JJerryChoi/apex-memory/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "better-sqlite3": "^11.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  }
+}