@jcyamacho/agent-memory 0.0.2 → 0.0.4

package/README.md

@@ -13,6 +13,18 @@ decisions across sessions.
 
 ## Quick Start
 
+Claude CLI:
+
+```bash
+claude mcp add --scope user memory -- npx -y @jcyamacho/agent-memory
+```
+
+Codex CLI:
+
+```bash
+codex mcp add memory -- npx -y @jcyamacho/agent-memory
+```
+
 Example MCP server config:
 
 ```json
@@ -51,22 +63,22 @@ With a custom database path:
 Recommended LLM instructions to pair with this MCP:
 
 ```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.
-
-Store concise, self-contained facts or short notes. Include `source`,
-`workspace`, and `session` when available so future retrieval is better scoped.
-
-Do not store secrets, credentials, API keys, tokens, or temporary noise.
-
-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.
+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 `workspace` to bias ranking toward the current project. Use `created_*`
+only for exact scoping.
 ```
 
 ## What It Stores
@@ -76,7 +88,7 @@ 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
-- Session-linked notes that still matter later
+- Project-scoped notes that still matter later
 
 ## Tools
 
@@ -87,16 +99,12 @@ Save durable context for later recall.
 Inputs:
 
 - `content` -> fact, preference, decision, or context to store
-- `source` -> client, tool, or agent name
 - `workspace` -> repository or workspace path
-- `session` -> conversation or execution session identifier
 
 Output:
 
 - `id`
-- `source`
 - `workspace`
-- `session`
 - `created_at`
 
 ### `recall`
@@ -105,19 +113,16 @@ Retrieve relevant memories for the current task.
 
 Inputs:
 
-- `query` -> keywords, names, facts, or phrases to search for
+- `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_source` -> ranking hint for a source
-- `preferred_workspace` -> ranking hint for a workspace
-- `filter_source` -> exact source filter
-- `filter_workspace` -> exact workspace filter
+- `workspace` -> workspace or repo path; biases ranking toward this workspace
 - `created_after` -> ISO 8601 lower bound
 - `created_before` -> ISO 8601 upper bound
 
 Output:
 
-- `results[]` with `id`, `content`, `score`, `source`, `workspace`, `session`,
-  and `created_at`
+- `results[]` with `id`, `content`, `score`, `workspace`, and `created_at`
 
 ## Setup
 
@@ -150,6 +155,9 @@ Set `AGENT_MEMORY_DB_PATH` when you want to:
 - share a memory DB across multiple clients
 - store the DB somewhere easier to back up or inspect
 
+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.
+
 ## Run from source
 
 If you are developing locally instead of using the published package:

package/dist/index.js

@@ -12464,7 +12464,7 @@ class StdioServerTransport {
   }
 }
 // package.json
-var version2 = "0.0.2";
+var version2 = "0.0.4";
 
 // src/config.ts
 import { homedir } from "node:os";
@@ -19881,6 +19881,9 @@ var EMPTY_COMPLETION_RESULT = {
   }
 };
 
+// src/memory-service.ts
+import { randomUUID } from "node:crypto";
+
 // src/errors.ts
 class MemoryError extends Error {
   code;
@@ -19905,6 +19908,63 @@ class PersistenceError extends MemoryError {
   }
 }
 
+// src/memory-service.ts
+var DEFAULT_LIMIT = 15;
+var MAX_LIMIT = 50;
+
+class MemoryService {
+  repository;
+  constructor(repository) {
+    this.repository = repository;
+  }
+  async save(input) {
+    const content = input.content.trim();
+    if (!content) {
+      throw new ValidationError("Memory content is required.");
+    }
+    const now = new Date;
+    const memory = {
+      id: randomUUID(),
+      content,
+      workspace: normalizeOptionalString(input.workspace),
+      createdAt: now,
+      updatedAt: now
+    };
+    return this.repository.save(memory);
+  }
+  async search(input) {
+    const terms = normalizeTerms(input.terms);
+    if (terms.length === 0) {
+      throw new ValidationError("At least one search term is required.");
+    }
+    const normalizedQuery = {
+      terms,
+      limit: normalizeLimit(input.limit),
+      workspace: normalizeOptionalString(input.workspace),
+      createdAfter: input.createdAfter,
+      createdBefore: input.createdBefore
+    };
+    return this.repository.search(normalizedQuery);
+  }
+}
+var normalizeLimit = (value) => {
+  if (value === undefined) {
+    return DEFAULT_LIMIT;
+  }
+  if (!Number.isInteger(value) || value < 1 || value > MAX_LIMIT) {
+    throw new ValidationError(`Limit must be an integer between 1 and ${MAX_LIMIT}.`);
+  }
+  return value;
+};
+var normalizeOptionalString = (value) => {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+};
+var normalizeTerms = (terms) => {
+  const normalizedTerms = terms.map((term) => term.trim()).filter(Boolean);
+  return [...new Set(normalizedTerms)];
+};
+
 // src/tools/shared.ts
 var toMcpError = (error2) => {
   if (error2 instanceof McpError) {
@@ -19932,23 +19992,18 @@ 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."),
-  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."),
+  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(MAX_LIMIT).optional().describe("Maximum number of memory results to return. Use a small number when you only need the best matches."),
+  workspace: string2().optional().describe("Workspace or repository path. Memories from this workspace rank higher, but other workspaces are not excluded."),
   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.")
 };
 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,24 +20012,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, 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,
+        workspace,
         createdAfter: parseOptionalDate(created_after, "created_after"),
         createdBefore: parseOptionalDate(created_before, "created_before")
       });
@@ -19983,17 +20026,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 +20050,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 +20062,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
@@ -20064,81 +20099,6 @@ var createMcpServer = (memoryService, version3) => {
   return server;
 };
 
-// src/memory-service.ts
-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;
-  constructor(repository) {
-    this.repository = repository;
-  }
-  async save(input) {
-    const content = input.content.trim();
-    if (!content) {
-      throw new ValidationError("Memory content is required.");
-    }
-    const now = new Date;
-    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 normalizedQuery = {
-      query,
-      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);
-  }
-}
-var normalizeLimit = (value) => {
-  if (value === undefined) {
-    return DEFAULT_LIMIT;
-  }
-  if (!Number.isInteger(value) || value < 1 || value > MAX_LIMIT) {
-    throw new ValidationError(`Limit must be an integer between 1 and ${MAX_LIMIT}.`);
-  }
-  return value;
-};
-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));
-};
-
 // src/sqlite-db.ts
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
@@ -20147,22 +20107,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
@@ -20208,9 +20165,7 @@ var initializeMemoryDatabase = (database) => {
 };
 
 // src/sqlite-repository.ts
-var CANDIDATE_MULTIPLIER = 5;
-var MIN_CANDIDATES = 25;
-var MAX_CANDIDATES = 100;
+var WORKSPACE_BIAS = 0.1;
 
 class SqliteMemoryRepository {
   database;
@@ -20221,9 +20176,7 @@ class SqliteMemoryRepository {
       INSERT INTO memories (
         id,
         content,
-        source,
         workspace,
-        session,
         created_at,
         updated_at
       ) VALUES (
@@ -20231,15 +20184,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 +20198,44 @@ 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);
-      }
-      if (query.filterWorkspace) {
-        whereClauses.push("m.workspace = ?");
-        params.push(query.filterWorkspace);
+      const selectParams = [];
+      const whereParams = [toFtsQuery(query.terms)];
+      let scoreExpr;
+      if (query.workspace) {
+        scoreExpr = "MAX(0, -bm25(memories_fts) + CASE WHEN m.workspace = ? THEN ? ELSE 0.0 END)";
+        selectParams.push(query.workspace, WORKSPACE_BIAS);
+      } else {
+        scoreExpr = "MAX(0, -bm25(memories_fts))";
       }
+      const whereClauses = ["memories_fts MATCH ?"];
       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, 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) {
@@ -20298,8 +20245,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.2",
+  "version": "0.0.4",
   "bin": {
     "agent-memory": "dist/index.js"
   },
@@ -23,7 +23,7 @@
     "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"