@jcyamacho/agent-memory 0.0.20 → 0.2.0

package/README.md

@@ -6,12 +6,11 @@ Persistent memory for MCP-powered coding agents.
 by SQLite. It helps your agent remember preferences, project context, and prior
 decisions across sessions.
 
-It exposes five tools:
+It exposes four tools:
 
 - `remember` -> save facts, decisions, preferences, and project context
-- `recall` -> retrieve the most relevant memories later
-- `review` -> browse all memories for a workspace
-- `revise` -> update an existing memory when it becomes outdated
+- `review` -> load workspace and global memories sorted by most recently updated
+- `revise` -> update an existing memory when its content changes or when it should become global
 - `forget` -> delete a memory that is no longer relevant
 
 ## Quick Start
@@ -44,24 +43,25 @@ OpenCode:
 
 ## Optional LLM Instructions
 
-Optional LLM instructions to reinforce the MCP's built-in guidance:
+Optional LLM instructions to reinforce the MCP's built-in guidance. The server
+instructions and tool descriptions already cover most behavior -- this prompt
+targets the habits models most commonly miss:
 
 ```md
 ## Agent Memory
 
-- Use `memory_recall` at conversation start and before design choices,
-  conventions, edge cases, or saving memory.
-- Query `memory_recall` with 2-5 short anchor-heavy terms or exact phrases,
-  not full questions or sentences.
-- Use `memory_review` to browse all memories for a workspace before bulk review
-  or cleanup.
-- Pass `workspace` for project-scoped memory. Omit it only for facts that
-  apply across projects.
-- Use `memory_remember` to save one durable fact when the user states a stable
-  preference, correction, or reusable project decision.
-- If the fact already exists, use `memory_revise` instead of creating a duplicate.
-- Use `memory_forget` to remove a wrong or obsolete memory.
-- Do not store secrets or temporary task state in memory.
+- Use `memory_review` at conversation start to load workspace memories into
+  context. During the session, use `memory_remember`, `memory_revise`, and
+  `memory_forget` to keep memories accurate.
+- Pass `workspace` on `memory_remember` for project-scoped memory. Omit it
+  only for facts that apply across projects.
+- Remember preferences, confirmed approaches, and decisions with reasoning
+  that would be lost after the session.
+- Revise content when a fact changes, promote a project-scoped memory to
+  global only when it truly applies across projects, and forget it when it is
+  no longer relevant.
+- Do not store secrets, temporary task state, or facts obvious from current
+  code or git history.
 ```
 
 ## Web UI
@@ -80,34 +80,22 @@ npx -y @jcyamacho/agent-memory@latest --ui --port 9090
 
 The web UI uses the same database as the MCP server.
 
-## How Recall Finds Memories
-
-`recall` uses a multi-signal ranking system to surface the most relevant
-memories:
-
-1. **Text relevance** is the primary signal -- memories whose content best
-   matches your search terms rank highest.
-2. **Workspace match** is the next strongest signal. When you pass
-   `workspace`, exact matches rank highest and all other scoped workspaces rank
-   below exact matches.
-3. **Embedding similarity** is a secondary signal. Recall builds an embedding
-   from your normalized search terms and boosts memories whose stored
-   embeddings are most semantically similar.
-4. **Global memories** (saved without a workspace) are treated as relevant
-   everywhere. When you pass `workspace`, they rank below exact workspace
-   matches and above memories from other workspaces.
-5. **Recency** is a minor tiebreaker -- newer memories rank slightly above older
-   ones when other signals are equal.
-
-If you omit `workspace`, recall still uses text relevance, embedding similarity,
-and recency. For best results, pass `workspace` whenever you have one. Save
-memories without a workspace only when they apply across all projects.
+## Mutating Tool Output
+
+`remember`, `revise`, and `forget` return the full affected memory
+as XML with `updated_at` and scope information so clients that hide tool-call
+arguments can still see what changed.
+`forget` includes `deleted="true"` on the returned `<memory>` element.
+
+## How Review Works
+
+`review` requires a `workspace` and returns memories saved in that workspace
+plus global memories (saved without a workspace), sorted by most recently
+updated. Results are paginated -- pass `page` to load older memories.
 
 When you save a memory from a git worktree, `agent-memory` stores the main repo
-root as the workspace. `recall` applies the same normalization to incoming
+root as the workspace. `review` applies the same normalization to incoming
 workspace queries so linked worktrees still match repo-scoped memories exactly.
-When that happens, recall returns the queried workspace value so callers can
-treat the match as belonging to their current worktree context.
 
 ## Configuration
 
@@ -131,26 +119,6 @@ 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
 
-### Model Cache Location
-
-By default, downloaded embedding model files are cached at:
-
-```text
-~/.config/agent-memory/models
-```
-
-Override it with:
-
-```bash
-AGENT_MEMORY_MODELS_CACHE_PATH=/absolute/path/to/models
-```
-
-Set `AGENT_MEMORY_MODELS_CACHE_PATH` when you want to:
-
-- keep model artifacts out of `node_modules`
-- share the model cache across reinstalls or multiple clients
-- store model downloads somewhere easier to inspect or manage
-
 Schema changes are migrated automatically, including workspace normalization for
 existing git worktree memories when the original path can still be resolved.