@jcyamacho/agent-memory 0.0.1 → 0.0.3

package/README.md

@@ -2,34 +2,93 @@
 
 Persistent memory for MCP-powered coding agents.
 
-`agent-memory` gives your LLM a durable memory layer backed by SQLite. It is a
-small MCP server with two focused tools:
+`agent-memory` is a stdio MCP server that gives your LLM durable memory backed
+by SQLite. It exposes two tools:
 
 - `remember` -> save facts, decisions, preferences, and project context
 - `recall` -> retrieve the most relevant memories later
 
-It is designed for agent workflows where context should survive across turns,
-sessions, and even different clients.
+Use it when your agent should remember preferences, project facts, and prior
+decisions across sessions.
 
-## Why Use It
+## Quick Start
 
-Most agents lose useful context between runs. This server lets them keep things
-that actually matter:
+Claude CLI:
 
-- User preferences like tone, formatting, and workflow habits
-- Project facts like architecture choices, paths, and constraints
-- Ongoing decisions like naming, scope, and tradeoffs
-- Session-specific notes that should still be discoverable later
+```bash
+claude mcp add --scope user memory -- npx -y @jcyamacho/agent-memory
+```
 
-The result is an agent that feels less stateless and less repetitive.
+Codex CLI:
 
-## Features
+```bash
+codex mcp add memory -- npx -y @jcyamacho/agent-memory
+```
 
-- SQLite-backed persistence with automatic database creation
-- Full-text recall with ranking, filters, and date bounds
-- Compact write acknowledgments to avoid wasting tokens
-- Durable memory scoped by `source`, `workspace`, and `session`
-- MCP-native tool descriptions optimized for LLM use
+Example MCP server config:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@jcyamacho/agent-memory"
+      ]
+    }
+  }
+}
+```
+
+With a custom database path:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@jcyamacho/agent-memory"
+      ],
+      "env": {
+        "AGENT_MEMORY_DB_PATH": "/absolute/path/to/memory.db"
+      }
+    }
+  }
+}
+```
+
+Recommended LLM instructions to pair with this MCP:
+
+```text
+Use `memory_recall` at task start and whenever prior preferences, project facts,
+or decisions may matter.
+
+Use `memory_remember` only for durable, reusable context: preferences,
+conventions, decisions, constraints, and stable workflow habits. Store one
+concise, self-contained fact per memory. Include `workspace` when available. Do
+not store secrets or temporary noise.
+
+For `memory_recall`, pass `terms` as 2-5 distinctive strings that describe what
+you are looking for. Prefer names, identifiers, package names, file names, and
+short phrases. Each term is matched independently — more terms cast a wider net,
+and results matching multiple terms rank higher. Stemming is applied
+automatically, so exact word forms are not required.
+
+Use `preferred_workspace` to bias ranking. Use `filter_workspace` and
+`created_*` only for exact scoping. Keep `limit` small.
+```
+
+## What It Stores
+
+This MCP is useful for context that should survive across turns and sessions:
+
+- User preferences like response style, formatting, and workflow habits
+- Project facts like paths, architecture choices, and conventions
+- Important decisions and constraints that should not be rediscovered
+- Project-scoped notes that still matter later
 
 ## Tools
 
@@ -39,17 +98,13 @@ Save durable context for later recall.
 
 Inputs:
 
-- `content` -> the fact, preference, decision, or context to remember
-- `source` -> where the memory came from, such as a client, tool, or agent
-- `workspace` -> repository or workspace path for project scoping
-- `session` -> conversation or execution session identifier
+- `content` -> fact, preference, decision, or context to store
+- `workspace` -> repository or workspace path
 
 Output:
 
 - `id`
-- `source`
 - `workspace`
-- `session`
 - `created_at`
 
 ### `recall`
@@ -58,50 +113,30 @@ Retrieve relevant memories for the current task.
 
 Inputs:
 
-- `query` -> keywords, facts, names, or phrases to search for
-- `limit` -> max results to return
-- `preferred_source` -> rank memories from this source higher
-- `preferred_workspace` -> rank memories from this workspace higher
-- `filter_source` -> only return memories from this exact source
-- `filter_workspace` -> only return memories from this exact workspace
+- `terms` -> 2-5 distinctive terms or short phrases that should appear in the
+  memory content; avoid full natural-language questions
+- `limit` -> maximum results to return
+- `preferred_workspace` -> ranking hint for a workspace
+- `filter_workspace` -> exact workspace filter
 - `created_after` -> ISO 8601 lower bound
 - `created_before` -> ISO 8601 upper bound
 
 Output:
 
-- `results[]` with `id`, `content`, `score`, `source`, `workspace`, `session`,
-  and `created_at`
-
-## Installation
+- `results[]` with `id`, `content`, `score`, `workspace`, and `created_at`
 
-### From npm
-
-```bash
-npm install -g @jcyamacho/agent-memory
-```
-
-### From source
-
-```bash
-bun install
-bun run build
-```
+## Setup
 
-The CLI entrypoint is:
+For normal usage:
 
-```bash
-agent-memory
-```
+- Node.js
 
-## Requirements
+For local development or running from source:
 
+- Bun
 - Node.js
-- A normal package install with `node_modules`
-
-Important: the build keeps `better-sqlite3` external on purpose. That is
-required for its native binding to load correctly at runtime.
 
-## Configuration
+### Database location
 
 By default, the SQLite database is created at:
 
@@ -115,48 +150,18 @@ Override it with:
 AGENT_MEMORY_DB_PATH=/absolute/path/to/memory.db
 ```
 
-Example:
-
-```bash
-AGENT_MEMORY_DB_PATH="$HOME/.local/share/agent-memory/memory.db" agent-memory
-```
+Set `AGENT_MEMORY_DB_PATH` when you want to:
 
-## Running It
+- keep memory in a project-specific location
+- share a memory DB across multiple clients
+- store the DB somewhere easier to back up or inspect
 
-### Development
+Beta note: schema changes are not migrated. If you are upgrading from an older
+beta, delete the existing memory DB and let the server create a new one.
 
-```bash
-bun install
-bun run build
-node dist/index.js
-```
+## Run from source
 
-### Local validation
-
-```bash
-bun lint
-bun test
-bun run build
-```
-
-## MCP Client Configuration
-
-Example MCP server entry:
-
-```json
-{
-  "mcpServers": {
-    "memory": {
-      "command": "agent-memory",
-      "env": {
-        "AGENT_MEMORY_DB_PATH": "/absolute/path/to/memory.db"
-      }
-    }
-  }
-}
-```
-
-If you are running from source instead of a global install, use:
+If you are developing locally instead of using the published package:
 
 ```json
 {
@@ -174,36 +179,29 @@ If you are running from source instead of a global install, use:
 }
 ```
 
-## Recommended LLM Instructions
-
-Copy and paste this into your system prompt, `AGENTS.md`, `CLAUDE.md`, or
-similar instruction file.
+Build first:
 
-```text
-Use `memory_recall` at the start of a task, when the user refers to previous
-context, or whenever prior preferences, project facts, or decisions may help.
-
-Use `memory_remember` to save durable context that will matter later, such as
-user preferences, project conventions, architecture decisions, constraints, and
-stable workflow habits.
+```bash
+bun install
+bun run build
+```
 
-Store concise, self-contained facts or short notes. Include `source`,
-`workspace`, and `session` when available so future retrieval is better scoped.
+## Local Development
 
-Do not store secrets, credentials, API keys, tokens, or temporary noise.
+Only needed if you want to work on the project itself.
 
-When recalling, use short factual queries and keep `limit` small unless you
-need broader recall. Use `preferred_workspace` or `preferred_source` to bias
-ranking, and `filter_workspace` or `filter_source` only when exact scoping is
-required.
+```bash
+bun install
+bun lint
+bun test
+bun run build
 ```
 
-## Development Notes
+## Notes
 
-- Runtime target is Node-compatible output at `dist/index.js`
-- Local workflows use Bun
-- Tests use `bun:test`
-- Runtime code avoids Bun-only APIs
+- `better-sqlite3` stays external in the build so its native binding loads
+  correctly at runtime.
+- Runtime output is Node-compatible and built to `dist/index.js`.
 
 ## License
 

package/dist/index.js

@@ -12464,7 +12464,7 @@ class StdioServerTransport {
   }
 }
 // package.json
-var version2 = "0.0.1";
+var version2 = "0.0.3";
 
 // src/config.ts
 import { homedir } from "node:os";
@@ -19932,11 +19932,9 @@ var parseOptionalDate = (value, fieldName) => {
 
 // src/tools/recall.ts
 var recallInputSchema = {
-  query: string2().describe("What to look for in memory. Use keywords, short phrases, names, decisions, or facts that should match previously remembered context."),
+  terms: array(string2()).min(1).describe("Search terms to match against remembered content. Use distinctive keywords, IDs, names, file names, or short phrases as separate items."),
   limit: number2().int().min(1).max(20).optional().describe("Maximum number of memory results to return. Use a small number when you only need the best matches."),
-  preferred_source: string2().optional().describe("Preferred source to rank higher when relevant, such as a client, tool, or agent name. This does not exclude other sources."),
   preferred_workspace: string2().optional().describe("Preferred workspace or repository path to rank higher when relevant. This does not exclude other workspaces."),
-  filter_source: string2().optional().describe("Only return memories from this exact source."),
   filter_workspace: string2().optional().describe("Only return memories from this exact workspace or repository path."),
   created_after: string2().optional().describe("Only return memories created at or after this ISO 8601 timestamp."),
   created_before: string2().optional().describe("Only return memories created at or before this ISO 8601 timestamp.")
@@ -19944,11 +19942,9 @@ var recallInputSchema = {
 var recallOutputSchema = {
   results: array(object({
     id: string2().describe("Stable identifier for the remembered item."),
-    content: string2().describe("The remembered content that matched the query."),
+    content: string2().describe("The remembered content that matched the search terms."),
     score: number2().describe("Relevance score for this result. Higher means a better match."),
-    source: string2().optional().describe("Source associated with the memory, if available."),
     workspace: string2().optional().describe("Workspace associated with the memory, if available."),
-    session: string2().optional().describe("Session associated with the memory, if available."),
     created_at: string2().describe("ISO 8601 timestamp showing when the memory was created.")
   }))
 };
@@ -19957,23 +19953,12 @@ var registerRecallTool = (server, memoryService) => {
     description: "Retrieve previously remembered context that may help with the current task. Use it for user preferences, project facts, prior decisions, constraints, or earlier conversation details.",
     inputSchema: recallInputSchema,
     outputSchema: recallOutputSchema
-  }, async ({
-    query,
-    limit,
-    preferred_source,
-    preferred_workspace,
-    filter_source,
-    filter_workspace,
-    created_after,
-    created_before
-  }) => {
+  }, async ({ terms, limit, preferred_workspace, filter_workspace, created_after, created_before }) => {
     try {
       const results = await memoryService.search({
-        query,
+        terms,
         limit,
-        preferredSource: preferred_source,
         preferredWorkspace: preferred_workspace,
-        filterSource: filter_source,
         filterWorkspace: filter_workspace,
         createdAfter: parseOptionalDate(created_after, "created_after"),
         createdBefore: parseOptionalDate(created_before, "created_before")
@@ -19983,17 +19968,17 @@ var registerRecallTool = (server, memoryService) => {
           id: result.id,
           content: result.content,
           score: result.score,
-          source: result.source,
           workspace: result.workspace,
-          session: result.session,
           created_at: result.createdAt.toISOString()
         }))
       };
+      const matchCount = structuredContent.results.length;
+      const summary = matchCount === 1 ? "Found 1 matching memory." : `Found ${matchCount} matching memories.`;
       return {
         content: [
           {
             type: "text",
-            text: JSON.stringify(structuredContent, null, 2)
+            text: summary
           }
         ],
         structuredContent
@@ -20007,15 +19992,11 @@ var registerRecallTool = (server, memoryService) => {
 // src/tools/remember.ts
 var rememberInputSchema = {
   content: string2().describe("The exact fact, preference, decision, or context to remember for future retrieval. Use a self-contained sentence or short note."),
-  source: string2().optional().describe("Where this memory came from, such as the client, tool, or agent name. Helps with filtering and ranking later."),
-  workspace: string2().optional().describe("Repository or workspace path this memory belongs to. Use it to keep memories scoped to a project."),
-  session: string2().optional().describe("Conversation or execution session identifier. Useful for tying memories back to one run or thread.")
+  workspace: string2().optional().describe("Repository or workspace path this memory belongs to. Use it to keep memories scoped to a project.")
 };
 var rememberOutputSchema = {
   id: string2().describe("Stable identifier for the saved memory."),
-  source: string2().optional().describe("Source stored with the memory, if provided."),
   workspace: string2().optional().describe("Workspace stored with the memory, if provided."),
-  session: string2().optional().describe("Session stored with the memory, if provided."),
   created_at: string2().describe("ISO 8601 timestamp showing when the memory was created.")
 };
 var registerRememberTool = (server, memoryService) => {
@@ -20023,26 +20004,22 @@ var registerRememberTool = (server, memoryService) => {
     description: "Save durable context for later recall. Use this for user preferences, project facts, decisions, constraints, or other information worth remembering across turns and tools.",
     inputSchema: rememberInputSchema,
     outputSchema: rememberOutputSchema
-  }, async ({ content, source, workspace, session }) => {
+  }, async ({ content, workspace }) => {
     try {
       const memory = await memoryService.save({
         content,
-        source,
-        workspace,
-        session
+        workspace
       });
       const structuredContent = {
         id: memory.id,
-        source: memory.source,
         workspace: memory.workspace,
-        session: memory.session,
         created_at: memory.createdAt.toISOString()
       };
       return {
         content: [
           {
             type: "text",
-            text: JSON.stringify(structuredContent, null, 2)
+            text: "Saved memory."
           }
         ],
         structuredContent
@@ -20068,8 +20045,6 @@ var createMcpServer = (memoryService, version3) => {
 import { randomUUID } from "node:crypto";
 var DEFAULT_LIMIT = 5;
 var MAX_LIMIT = 20;
-var SOURCE_BIAS = 0.15;
-var WORKSPACE_BIAS = 0.1;
 
 class MemoryService {
   repository;
@@ -20085,34 +20060,27 @@ class MemoryService {
     const memory = {
       id: randomUUID(),
       content,
-      source: normalizeOptionalString(input.source),
       workspace: normalizeOptionalString(input.workspace),
-      session: normalizeOptionalString(input.session),
       createdAt: now,
       updatedAt: now
     };
     return this.repository.save(memory);
   }
   async search(input) {
-    const query = input.query.trim();
-    if (!query) {
-      throw new ValidationError("Search query is required.");
+    const terms = normalizeTerms(input.terms);
+    if (terms.length === 0) {
+      throw new ValidationError("At least one search term is required.");
     }
     const normalizedQuery = {
-      query,
+      terms,
       limit: normalizeLimit(input.limit),
-      preferredSource: normalizeOptionalString(input.preferredSource),
       preferredWorkspace: normalizeOptionalString(input.preferredWorkspace),
-      filterSource: normalizeOptionalString(input.filterSource),
       filterWorkspace: normalizeOptionalString(input.filterWorkspace),
       createdAfter: input.createdAfter,
       createdBefore: input.createdBefore
     };
     const results = await this.repository.search(normalizedQuery);
-    return results.map((result) => ({
-      ...result,
-      score: rankResult(result, normalizedQuery)
-    })).sort((left, right) => right.score - left.score).slice(0, normalizedQuery.limit);
+    return results.slice(0, normalizedQuery.limit);
   }
 }
 var normalizeLimit = (value) => {
@@ -20128,15 +20096,9 @@ var normalizeOptionalString = (value) => {
   const trimmed = value?.trim();
   return trimmed ? trimmed : undefined;
 };
-var rankResult = (result, query) => {
-  let score = result.score;
-  if (query.preferredSource && result.source === query.preferredSource) {
-    score += SOURCE_BIAS;
-  }
-  if (query.preferredWorkspace && result.workspace === query.preferredWorkspace) {
-    score += WORKSPACE_BIAS;
-  }
-  return Number(score.toFixed(6));
+var normalizeTerms = (terms) => {
+  const normalizedTerms = terms.map((term) => term.trim()).filter(Boolean);
+  return [...new Set(normalizedTerms)];
 };
 
 // src/sqlite-db.ts
@@ -20147,22 +20109,19 @@ var MEMORY_SCHEMA = `
   CREATE TABLE IF NOT EXISTS memories (
     id TEXT PRIMARY KEY,
     content TEXT NOT NULL,
-    source TEXT,
     workspace TEXT,
-    session TEXT,
     created_at INTEGER NOT NULL,
     updated_at INTEGER NOT NULL
   );
 
   CREATE INDEX IF NOT EXISTS idx_memories_created_at ON memories(created_at);
-  CREATE INDEX IF NOT EXISTS idx_memories_source ON memories(source);
   CREATE INDEX IF NOT EXISTS idx_memories_workspace ON memories(workspace);
 
   CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
     content,
     content = 'memories',
     content_rowid = 'rowid',
-    tokenize = 'unicode61'
+    tokenize = 'porter unicode61'
   );
 
   CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
@@ -20211,6 +20170,7 @@ var initializeMemoryDatabase = (database) => {
 var CANDIDATE_MULTIPLIER = 5;
 var MIN_CANDIDATES = 25;
 var MAX_CANDIDATES = 100;
+var WORKSPACE_BIAS = 0.1;
 
 class SqliteMemoryRepository {
   database;
@@ -20221,9 +20181,7 @@ class SqliteMemoryRepository {
       INSERT INTO memories (
         id,
         content,
-        source,
         workspace,
-        session,
         created_at,
         updated_at
       ) VALUES (
@@ -20231,15 +20189,13 @@ class SqliteMemoryRepository {
         ?,
         ?,
         ?,
-        ?,
-        ?,
         ?
       )
     `);
   }
   async save(memory) {
     try {
-      this.insertStatement.run(memory.id, memory.content, memory.source, memory.workspace, memory.session, memory.createdAt.getTime(), memory.updatedAt.getTime());
+      this.insertStatement.run(memory.id, memory.content, memory.workspace, memory.createdAt.getTime(), memory.updatedAt.getTime());
       return memory;
     } catch (error2) {
       throw new PersistenceError("Failed to save memory.", { cause: error2 });
@@ -20247,48 +20203,48 @@ class SqliteMemoryRepository {
   }
   async search(query) {
     try {
-      const whereClauses = ["memories_fts MATCH ?"];
-      const params = [toFtsQuery(query.query)];
-      if (query.filterSource) {
-        whereClauses.push("m.source = ?");
-        params.push(query.filterSource);
+      const selectParams = [];
+      const whereParams = [toFtsQuery(query.terms)];
+      let scoreExpr;
+      if (query.preferredWorkspace) {
+        scoreExpr = "MAX(0, -bm25(memories_fts) + CASE WHEN m.workspace = ? THEN ? ELSE 0.0 END)";
+        selectParams.push(query.preferredWorkspace, WORKSPACE_BIAS);
+      } else {
+        scoreExpr = "MAX(0, -bm25(memories_fts))";
       }
+      const whereClauses = ["memories_fts MATCH ?"];
       if (query.filterWorkspace) {
         whereClauses.push("m.workspace = ?");
-        params.push(query.filterWorkspace);
+        whereParams.push(query.filterWorkspace);
       }
       if (query.createdAfter) {
         whereClauses.push("m.created_at >= ?");
-        params.push(query.createdAfter.getTime());
+        whereParams.push(query.createdAfter.getTime());
       }
       if (query.createdBefore) {
         whereClauses.push("m.created_at <= ?");
-        params.push(query.createdBefore.getTime());
+        whereParams.push(query.createdBefore.getTime());
       }
+      const params = [...selectParams, ...whereParams, toCandidateLimit(query.limit)];
       const statement = this.database.prepare(`
         SELECT
           m.id,
           m.content,
-          m.source,
           m.workspace,
-          m.session,
           m.created_at,
-          MAX(0, -bm25(memories_fts)) AS score
+          ${scoreExpr} AS score
         FROM memories_fts
         INNER JOIN memories AS m ON m.rowid = memories_fts.rowid
         WHERE ${whereClauses.join(" AND ")}
-        ORDER BY bm25(memories_fts)
+        ORDER BY score DESC
         LIMIT ?
       `);
-      params.push(toCandidateLimit(query.limit));
       const rows = statement.all(...params);
       return rows.map((row) => ({
         id: row.id,
         content: row.content,
         score: row.score,
-        source: row.source ?? undefined,
         workspace: row.workspace ?? undefined,
-        session: row.session ?? undefined,
         createdAt: new Date(row.created_at)
       }));
     } catch (error2) {
@@ -20299,7 +20255,14 @@ class SqliteMemoryRepository {
   }
 }
 var toCandidateLimit = (limit) => Math.min(Math.max(limit * CANDIDATE_MULTIPLIER, MIN_CANDIDATES), MAX_CANDIDATES);
-var toFtsQuery = (query) => query.trim().split(/\s+/).filter(Boolean).map((term) => `"${term.replaceAll('"', '""')}"`).join(" ");
+var toFtsQuery = (terms) => terms.map(toFtsTerm).join(" OR ");
+var toFtsTerm = (term) => {
+  const escaped = term.replaceAll('"', '""');
+  if (term.includes(" ")) {
+    return `"${escaped}"`;
+  }
+  return `"${escaped}"*`;
+};
 
 // src/index.ts
 var { databasePath } = resolveConfig();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jcyamacho/agent-memory",
   "main": "dist/index.js",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "bin": {
     "agent-memory": "dist/index.js"
   },
@@ -23,7 +23,10 @@
     "build": "bun build src/index.ts --target=node --external better-sqlite3 --outfile dist/index.js --banner \"#!/usr/bin/env node\"",
     "start": "node dist/index.js",
     "test": "bun test",
-    "lint": "biome check --write"
+    "lint": "biome check --write && tsc --noEmit",
+    "release:patch": "npm version patch && git push origin main --follow-tags",
+    "release:minor": "npm version minor && git push origin main --follow-tags",
+    "release:major": "npm version major && git push origin main --follow-tags"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.6",