@j0hanz/memdb 1.2.3 → 1.2.5

package/dist/instructions.md

@@ -1,92 +1,173 @@
-# memdb MCP Server Instructions
+# memdb MCP Server — AI Usage Instructions
 
-This server provides **local, SQLite-backed long-term memory**. Use it to store, retrieve, and organize short text memories (notes, facts, decisions, lessons) with tags and optional relationships.
+Use this server to store and retrieve persistent memories (facts, decisions, lessons, plans) in a local SQLite database. Prefer these tools over "remembering" state in chat.
 
-## Scope & Constraints
+## Operating Rules
 
-- This server only manages memories in a local SQLite DB (default: `<cwd>/.memdb/memory.db`). It does not read/write project files.
-- All tool results return JSON in `structuredContent` with `{ ok: true, result }` or `{ ok: false, error }`.
-- Memory identity is an MD5 `hash` (32 hex chars). Changing content changes the hash.
-- Tags and relation types must not contain whitespace (use `kebab-case`).
+- Use tools only when the operation changes or verifies memory state.
+- Prefer `search_memories` or `memory_stats` to establish state before updating/deleting.
+- Operate by stable identifiers (`hash`, 32-char hex MD5) rather than ambiguous user text.
+- Treat destructive tools (`delete_memory`, `delete_memories`, `delete_relationship`) as destructive: require explicit user confirmation unless clearly requested.
+- Keep operations atomic; if a request is vague, ask a clarifying question.
+- **Client UX:** Tool lists can be cached (reset via "MCP: Reset Cached Tools"). Only run MCP servers from trusted sources.
 
-## Tool Guide
+### Strategies
 
-### Store
+- **Discovery:** Start with `search_memories` or `memory_stats` to discover what exists. Use `recall` (depth 1-2) when you need connected context.
+- **Action:** Use `store_memories` for batch imports (up to 50). Prefer `update_memory` to fix content (preserves history/context better than delete+create). Always confirm explicit deletions with the user.
 
-- `store_memory`: Create or deduplicate a single memory.
-  - Use when you have one clear item.
-  - Provide `tags` (1–100). Optional: `importance` (0–10), `memory_type`.
-- `store_memories`: Batch store up to 50 memories.
-  - Use for importing many items; supports partial success.
+## Data Model
 
-### Find & Read
+- **Memory:**
+  - `hash` (MD5 of content, primary key)
+  - `content` (1–100k chars)
+  - `tags` (1–100 items, no whitespace, `kebab-case`)
+  - `importance` (0–10, 10=critical)
+  - `memory_type` (`general`, `fact`, `plan`, `decision`, `reflection`, `lesson`, `error`, `gradient`)
+- **Relationship:** Directed edge (`from_hash` → `to_hash`) with a typed label (`relation_type`).
 
-- `search_memories`: Search across content + tags.
-  - Use first for discovery.
-  - Prefer specific queries and tags (include tag text in the query).
-- `get_memory`: Fetch a memory by `hash`.
-  - Use after search results identify a specific `hash`.
+## Workflows
 
-### Update
+### 1) Capture a new memory
 
-- `update_memory`: Replace content (and optionally replace tags) for a given `hash`.
-  - Use to correct or refine a memory.
-  - Expect a new `hash` in the result.
+1. Prepare content (crisp, 1–3 sentences).
+2. Choose 2–6 tags: domain tags (`auth`, `postgres`) + intent tags (`decision`, `bug`).
+3. Call `store_memory`. Record the returned `hash` if you need to reference it later.
 
-### Delete (Destructive)
+### 2) Retrieve context for a task
 
-- `delete_memory`: Delete a single memory by `hash`.
-- `delete_memories`: Batch delete up to 50 hashes.
+1. Call `search_memories` with a focused query (include relevant tag text in the query).
+2. If you need related context, call `recall` with `depth: 1` or `2`.
+3. For verbatim content of a specific hash, call `get_memory`.
 
-Use delete tools only when the user explicitly wants removal.
+### 3) Maintain quality over time
 
-### Relationships (Knowledge Graph)
+1. Prefer `update_memory` over creating duplicates when correcting content.
+2. Use `create_relationship` to link durable facts/decisions in the knowledge graph.
+3. Use `delete_memory` / `delete_memories` only with explicit user intent.
 
-- `create_relationship`: Create a typed edge `from_hash` → `to_hash`.
-  - Use to connect related memories (e.g., `depends_on`, `causes`, `part_of`).
-- `get_relationships`: List relationships for a memory.
-  - Use to inspect the local graph around one memory.
-- `delete_relationship`: Remove a relationship.
-  - Use when an edge is wrong/outdated.
+## Tools
 
-### Deep Recall
+### store_memory
 
-- `recall`: Search + traverse relationships to return a connected cluster.
-  - Use when you need broader context beyond keyword matches.
-  - `depth` controls hops (0–3). Use 1–2 by default.
+Store a single memory with tags.
 
-### Health / Overview
+- **Use when:** You have one clear item to persist.
+- **Args:** `content` (req), `tags` (req), `importance` (opt), `memory_type` (opt).
+- **Returns:** `{ id, hash, isNew }`.
 
-- `memory_stats`: Returns database stats (counts, oldest/newest).
-  - Use to sanity-check the DB or report status.
+### store_memories
 
-## Recommended Workflows
+Batch store up to 50 memories.
 
-### Capture a new memory (single)
+- **Use when:** Importing multiple items at once.
+- **Args:** `items[]` (each has `content`, `tags`, optional `importance`, `memory_type`).
+- **Returns:** `{ results, succeeded, failed }`.
 
-1. Choose crisp content (1–3 sentences).
-2. Choose stable tags (topic + type), e.g. `auth`, `decision`, `bug`, `postgres`.
-3. Call `store_memory`.
+### search_memories
 
-### Retrieve context for a task
+Full-text + tag search.
 
-1. Use `search_memories` with a focused query.
-2. If you need related context, use `recall` (depth 1–2).
-3. Use `get_memory` for any specific hash you need verbatim.
+- **Use when:** Discovering what exists; start here before mutating.
+- **Args:** `query` (1–1,000 chars).
+- **Returns:** Array of `Memory` + `relevance`, up to 100 results.
+- **Notes:** Content matches rank higher than tag matches.
 
-### Maintain quality over time
+### get_memory
 
-1. Prefer `update_memory` over creating duplicates when you are correcting an existing item.
-2. Use `create_relationship` to connect durable facts/decisions.
-3. Use delete tools only with explicit user intent.
+Fetch a single memory by hash.
 
-## Tagging & Memory Type Guidelines
+- **Use when:** You need verbatim content after search identified a hash.
+- **Args:** `hash` (32 hex chars).
+- **Returns:** `Memory` object.
 
-- Prefer 2–6 tags per memory: 1–2 domain tags + 1–2 intent tags.
-- `memory_type` is optional; use it when it helps retrieval: `fact`, `decision`, `plan`, `lesson`, `error`, `reflection`, `gradient`, `general`.
-- Use `importance` to surface critical items (0=low, 10=critical).
+### update_memory
 
-## Safety
+Update content (and optionally replace tags).
 
-- Do not store secrets (API keys, passwords, tokens, private keys) in memory content.
-- Confirm destructive operations (`delete_*`, `delete_relationship`) before calling them.
+- **Use when:** Correcting or refining an existing memory.
+- **Args:** `hash` (req), `content` (req), `tags` (opt, replaces all).
+- **Returns:** `{ updated: true, oldHash, newHash }`.
+- **Notes:** Hash changes because content changes (content-addressed).
+
+### delete_memory
+
+Delete a single memory by hash.
+
+- **Use when:** User explicitly wants removal.
+- **Args:** `hash`.
+- **Returns:** `{ deleted: true }` or error if not found.
+
+### delete_memories
+
+Batch delete up to 50 hashes.
+
+- **Use when:** Bulk cleanup with explicit user intent.
+- **Args:** `hashes[]`.
+- **Returns:** `{ results, succeeded, failed }`.
+
+### create_relationship
+
+Link two memories with a typed edge.
+
+- **Use when:** Building a knowledge graph (e.g., `depends_on`, `causes`, `part_of`).
+- **Args:** `from_hash`, `to_hash`, `relation_type`.
+- **Returns:** `{ id, isNew }`.
+
+### get_relationships
+
+List relationships for a memory.
+
+- **Use when:** Inspecting local graph around one memory.
+- **Args:** `hash`, `direction` (opt: `outgoing`, `incoming`, `both`; default `both`).
+- **Returns:** Array of `Relationship` objects.
+
+### delete_relationship
+
+Remove a relationship edge.
+
+- **Use when:** An edge is wrong or outdated.
+- **Args:** `from_hash`, `to_hash`, `relation_type`.
+- **Returns:** `{ deleted: true }`.
+
+### recall
+
+Search + traverse relationships to return a connected cluster.
+
+- **Use when:** You need broader context beyond keyword matches.
+- **Args:** `query`, `depth` (opt, 0–3; default 1).
+- **Returns:** `{ memories, relationships, depth }`.
+
+### memory_stats
+
+Database statistics and health.
+
+- **Use when:** Sanity-checking the DB or reporting status.
+- **Args:** (none).
+- **Returns:** `{ memoryCount, tagCount, oldestMemory, newestMemory }`.
+
+## Response Shape
+
+Success: `{ "ok": true, "result": { ... } }`
+Error: `{ "ok": false, "error": { "code": "E_...", "message": "..." } }`
+
+### Common Errors
+
+| Code            | Meaning                       | Resolution                          |
+| --------------- | ----------------------------- | ----------------------------------- |
+| `E_NOT_FOUND`   | Memory/Relationship not found | Check hash or create new            |
+| `E_INVALID_ARG` | Validation failed (zod)       | Check limits, types, and formatting |
+| `E_TOOL_ERROR`  | Internal/Db error             | Check server logs or stats          |
+
+## Limits
+
+- **Content Size:** 100,000 chars per memory
+- **Tag Count:** 100 per memory
+- **Tag Length:** 50 chars (no whitespace)
+- **Batch Size:** 50 items (store/delete)
+- **Query Length:** 1,000 chars
+
+## Security
+
+- **No Secrets:** Do not store API keys, passwords, or PII in memory content.
+- **Confirmation:** Always ask before using `delete_*` tools unless the user explicitly requested it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/memdb",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "mcpName": "io.github.j0hanz/memdb",
   "description": "A SQLite-backed MCP memory server with local workspace storage.",
   "type": "module",