clawmem 0.14.0 → 0.15.0

package/docs/reference/mcp-tools.md

@@ -0,0 +1,336 @@
+# MCP server tools reference
+
+Complete reference for ClawMem's MCP server tools. These let AI agents search, retrieve, and manage persistent memory. All tools accept an optional `vault` parameter for multi-vault setups. Omit for the default vault.
+
+## Retrieval
+
+### memory_retrieve
+
+**Recommended entry point.** Auto-classifies query and routes to the optimal backend.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | string | required | Your question or search query |
+| `mode` | enum | `auto` | Override: `keyword`, `semantic`, `causal`, `timeline`, `discovery`, `complex`, `hybrid` |
+| `limit` | number | 10 | Max results |
+| `compact` | boolean | true | Compact output (snippets vs full content) |
+| `vault` | string | — | Named vault |
+
+Auto-routing:
+- Timeline queries ("last session", "yesterday") → session history
+- Causal queries ("why did we", "what caused") → intent_search with graph traversal
+- Discovery queries ("similar to", "related to") → find_similar
+- Complex queries (multi-topic) → query_plan
+- Everything else → full hybrid search
+
+### query
+
+Full hybrid pipeline: BM25 + vector + query expansion + cross-encoder reranking.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | string | required | Search query |
+| `limit` | number | 10 | Max results |
+| `compact` | boolean | true | Compact output |
+| `collection` | string | — | Filter by collection (comma-separated for multi) |
+| `intent` | string | — | Domain hint for ambiguous queries (steers expansion, reranking, chunk selection) |
+| `candidateLimit` | number | 30 | Candidates for reranking (tune precision vs speed) |
+| `vault` | string | — | Named vault |
+
+BM25 strong-signal bypass: skips expansion when top BM25 hit >= 0.85 with gap >= 0.15 (disabled when `intent` is provided).
+
+### search
+
+BM25 only. Zero GPU cost.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | string | required | Search query |
+| `limit` | number | 10 | Max results |
+| `compact` | boolean | true | Compact output |
+| `collection` | string | — | Filter by collection |
+| `vault` | string | — | Named vault |
+
+### vsearch
+
+Vector only. Semantic similarity.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | string | required | Search query |
+| `limit` | number | 10 | Max results |
+| `compact` | boolean | true | Compact output |
+| `collection` | string | — | Filter by collection |
+| `vault` | string | — | Named vault |
+
+### intent_search
+
+Intent-classified search with graph traversal. Use directly for "why", "when", "who" questions.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | string | required | Search query |
+| `limit` | number | 10 | Max results |
+| `force_intent` | enum | — | Override: `WHY`, `WHEN`, `ENTITY`, `WHAT` |
+| `enable_graph_traversal` | boolean | true | Multi-hop graph expansion |
+| `vault` | string | — | Named vault |
+
+### query_plan
+
+Multi-topic decomposition. Use for complex queries spanning multiple subjects.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | string | required | Complex or multi-topic query |
+| `limit` | number | 10 | Max results |
+| `compact` | boolean | true | Compact output |
+| `vault` | string | — | Named vault |
+
+## Document access
+
+### get
+
+Retrieve a single document by path or docid.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `file` | string | required | File path or docid (`#abc123`) |
+| `fromLine` | number | — | Start line |
+| `maxLines` | number | — | Line limit |
+| `lineNumbers` | boolean | false | Include line numbers |
+| `vault` | string | — | Named vault |
+
+### multi_get
+
+Retrieve multiple documents by glob pattern or comma-separated list.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `pattern` | string | required | Glob pattern or comma-separated paths |
+| `maxLines` | number | — | Line limit per document |
+| `maxBytes` | number | 10240 | Max total bytes |
+| `lineNumbers` | boolean | false | Include line numbers |
+| `vault` | string | — | Named vault |
+
+### find_similar
+
+k-NN vector neighbors of a reference document.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `file` | string | required | Path of reference document |
+| `limit` | number | 5 | Max results |
+| `vault` | string | — | Named vault |
+
+### find_causal_links
+
+Trace causal decision chains from a document.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `docid` | string | required | Document ID |
+| `direction` | enum | `both` | `causes`, `caused_by`, or `both` |
+| `depth` | number | 5 | Max traversal depth (1-10) |
+| `vault` | string | — | Named vault |
+
+### timeline
+
+Temporal neighborhood — what was created/modified before and after a document.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `docid` | string | required | Document ID |
+| `before` | number | 5 | Documents to show before (1-20) |
+| `after` | number | 5 | Documents to show after (1-20) |
+| `same_collection` | boolean | false | Constrain to same collection |
+| `vault` | string | — | Named vault |
+
+### memory_evolution_status
+
+Track how a document's A-MEM metadata evolved over time.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `docid` | string | required | Document ID |
+| `limit` | number | 10 | Max evolution entries (1-100) |
+| `vault` | string | — | Named vault |
+
+### session_log
+
+Recent session history with handoffs and file changes.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `limit` | number | 10 | Max sessions |
+| `vault` | string | — | Named vault |
+
+## Mutations
+
+### memory_pin
+
+Pin a memory for permanent prioritization (+0.3 composite boost).
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | string | required | Search query or path to find the memory |
+| `unpin` | boolean | false | Set true to unpin |
+| `vault` | string | — | Named vault |
+
+### memory_snooze
+
+Temporarily hide a memory from context surfacing.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | string | required | Search query or path to find the memory |
+| `until` | string | — | ISO date (e.g., `2026-04-01`). Omit to unsnooze. |
+| `vault` | string | — | Named vault |
+
+### memory_forget
+
+Permanently deactivate a memory.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | string | required | Search query or path to find the memory |
+| `confirm` | boolean | true | False = preview only |
+| `vault` | string | — | Named vault |
+
+**Search behavior (v0.2.6+, all three tools):** Query matching cascades through four strategies: exact path match → BM25 full-text → title-token overlap → vector similarity. This prevents "No matching memory found" errors when the document exists but BM25 fails to match (e.g., too many AND'd terms). Path-like queries (containing `/` or ending in `.md`) try direct path matching first. `memory_forget` requires higher confidence to act — ambiguous matches return candidates instead of mutating.
+
+## Lifecycle
+
+### lifecycle_status
+
+Document lifecycle statistics: active, archived, forgotten, pinned, snoozed counts.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `vault` | string | — | Named vault |
+
+### lifecycle_sweep
+
+Archive stale documents based on lifecycle policy.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `dry_run` | boolean | true | Preview only (no action) |
+| `vault` | string | — | Named vault |
+
+### lifecycle_restore
+
+Restore auto-archived documents.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | string | — | Search archived docs by keyword |
+| `collection` | string | — | Restore all from a collection |
+| `all` | boolean | false | Restore everything |
+| `vault` | string | — | Named vault |
+
+## Maintenance
+
+### status
+
+Quick index health check.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `vault` | string | — | Named vault |
+
+### reindex
+
+Trigger re-scan of all collections.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `vault` | string | — | Named vault |
+
+### index_stats
+
+Detailed statistics: content type distribution, staleness, embedding coverage.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `vault` | string | — | Named vault |
+
+### build_graphs
+
+Build temporal backbone and semantic graph.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `graph_types` | array | `["all"]` | `temporal`, `semantic`, or `all` |
+| `semantic_threshold` | number | 0.7 | Similarity threshold for semantic edges |
+| `vault` | string | — | Named vault |
+
+### profile
+
+Get or rebuild the user profile (static facts + dynamic context).
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `rebuild` | boolean | false | Force rebuild |
+
+### beads_sync
+
+Sync Beads issues from Dolt backend into the search index.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `project_path` | string | cwd | Path to project with `.beads/` directory |
+
+## Vault management
+
+### list_vaults
+
+Show configured vault names and paths. Returns empty in single-vault mode.
+
+### vault_sync
+
+Index markdown from a directory into a named vault.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `vault` | string | required | Target vault name |
+| `content_root` | string | required | Directory path to index |
+| `pattern` | string | `**/*.md` | Glob pattern |
+| `collection_name` | string | vault name | Collection name in the vault |
+
+Restricted-path validation rejects sensitive directories (`/etc/`, `/root/`, `.ssh`, `.env`, `credentials`, `.aws`, `.kube`).
+
+### kg_query
+
+Query the SPO knowledge graph for an entity's temporal relationships.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `entity` | string | required | Entity name or ID |
+| `as_of` | string | — | Date filter (YYYY-MM-DD) — only facts valid at this date |
+| `direction` | enum | `both` | `outgoing`, `incoming`, or `both` |
+| `vault` | string | — | Named vault |
+
+Uses entity resolution (FTS search) first, falls back to slug normalization. Returns triples with subject, predicate, object, valid_from, valid_to, confidence, and current status.
+
+### diary_write
+
+Write to the agent's diary. For non-hooked environments where hooks don't capture session context automatically.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `entry` | string | required | Diary entry text |
+| `topic` | string | `general` | Topic tag (e.g., 'technical', 'user_facts', 'session') |
+| `agent` | string | `agent` | Agent name writing the entry |
+| `vault` | string | — | Named vault |
+
+Entries stored via `saveMemory()` with ms-resolution paths to prevent dedup of rapid writes.
+
+### diary_read
+
+Read recent diary entries.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `last_n` | number | 10 | Number of entries to return |
+| `agent` | string | — | Filter by agent name |
+| `vault` | string | — | Named vault |

package/docs/reference/rest-api.md

@@ -0,0 +1,204 @@
+# ClawMem REST API reference
+
+HTTP REST API for non-MCP clients, web dashboards, cross-machine access, and **OpenClaw agent tools**. Required for OpenClaw integration — the memory plugin serves 5 agent tools (search, get, session_log, timeline, similar) via this API. See the [OpenClaw plugin guide](../guides/openclaw-plugin.md) for details.
+
+## Start the server
+
+```bash
+./bin/clawmem serve                          # localhost:7438, no auth
+./bin/clawmem serve --port 8080              # custom port
+CLAWMEM_API_TOKEN=secret ./bin/clawmem serve # with bearer token auth
+```
+
+## Authentication
+
+Set `CLAWMEM_API_TOKEN` to require `Authorization: Bearer <token>` on all requests. If unset, access is open (localhost-only by default).
+
+## Endpoints
+
+### Health & stats
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Liveness probe — returns status, version, doc count |
+| GET | `/stats` | Full index statistics with collection list |
+
+### Search & retrieval
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/search` | Direct search with mode selection |
+| POST | `/retrieve` | Smart retrieve with auto-routing |
+
+**POST /search**
+
+```json
+{
+  "query": "authentication decisions",
+  "mode": "hybrid",
+  "collection": "notes",
+  "compact": true,
+  "limit": 10
+}
+```
+
+Modes: `auto`, `keyword`, `semantic`, `hybrid`.
+
+**POST /retrieve**
+
+```json
+{
+  "query": "why did we choose JWT",
+  "mode": "auto",
+  "compact": true,
+  "limit": 10
+}
+```
+
+Modes: `auto`, `keyword`, `semantic`, `causal`, `timeline`, `hybrid`.
+
+Auto-routing classifies the query:
+- Causal queries → intent-aware RRF (boosts vector for WHY, BM25 for WHEN)
+- Timeline queries → session history
+- Short keyword queries → BM25
+- Conceptual queries → vector
+- Everything else → hybrid
+
+```bash
+# Example: causal query
+curl -X POST http://localhost:7438/retrieve \
+  -H 'Content-Type: application/json' \
+  -d '{"query": "why did we switch to JWT", "compact": true}'
+
+# Example: keyword search
+curl -X POST http://localhost:7438/search \
+  -H 'Content-Type: application/json' \
+  -d '{"query": "CLAWMEM_EMBED_URL", "mode": "keyword"}'
+```
+
+### Documents
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/documents/:docid` | Single document by 6-char hash prefix |
+| GET | `/documents?pattern=...` | Multi-get by glob pattern |
+
+```bash
+curl http://localhost:7438/documents/a1b2c3
+curl http://localhost:7438/documents?pattern=notes/*.md
+```
+
+### Timeline & sessions
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/timeline/:docid` | Temporal neighborhood (before/after) |
+| GET | `/sessions` | Recent session history |
+
+```bash
+curl http://localhost:7438/timeline/a1b2c3?before=3&after=3
+curl http://localhost:7438/sessions?limit=5
+```
+
+### Graph traversal
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/graph/causal/:docid` | Causal chain traversal |
+| GET | `/graph/similar/:docid` | k-NN semantic neighbors |
+| GET | `/graph/evolution/:docid` | Document evolution timeline |
+
+```bash
+curl http://localhost:7438/graph/causal/a1b2c3?direction=both&depth=3
+curl http://localhost:7438/graph/similar/a1b2c3?limit=5
+```
+
+### Lifecycle
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/lifecycle/status` | Active/archived/pinned/snoozed counts |
+| POST | `/lifecycle/sweep` | Archive stale docs (dry_run default) |
+| POST | `/lifecycle/restore` | Restore archived docs |
+
+### Document mutations
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/documents/:docid/pin` | Pin/unpin a document |
+| POST | `/documents/:docid/snooze` | Snooze until a date |
+| POST | `/documents/:docid/forget` | Deactivate a document |
+
+### Maintenance
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/collections` | List all collections |
+| GET | `/profile` | Get user profile |
+| POST | `/reindex` | Trigger re-scan |
+| POST | `/graphs/build` | Rebuild temporal + semantic graphs |
+| GET | `/export` | Full vault export as JSON |
+
+## Response format
+
+All responses are JSON. Search/retrieve responses include:
+
+```json
+{
+  "query": "authentication",
+  "mode": "hybrid",
+  "count": 3,
+  "results": [
+    {
+      "docid": "a1b2c3",
+      "path": "notes/auth.md",
+      "title": "Authentication Decision",
+      "score": 0.847,
+      "contentType": "decision",
+      "snippet": "We chose JWT for authentication because..."
+    }
+  ]
+}
+```
+
+When `compact=false`, results include `modifiedAt`, `confidence`, and full `body` instead of `snippet`.
+
+## Running as a systemd service
+
+For production deployments (especially OpenClaw), run the REST API as a persistent service instead of relying on the plugin's `spawnBackground()`:
+
+```bash
+cat > ~/.config/systemd/user/clawmem-serve.service << 'EOF'
+[Unit]
+Description=ClawMem REST API server
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=%h/clawmem/bin/clawmem serve --port 7438
+Restart=on-failure
+RestartSec=5
+Environment=CLAWMEM_API_TOKEN=your-secret-here
+
+[Install]
+WantedBy=default.target
+EOF
+
+systemctl --user daemon-reload
+systemctl --user enable --now clawmem-serve.service
+```
+
+When running as a systemd service, set `enableTools: true` and `servePort: 7438` in the OpenClaw plugin manifest — the plugin will connect to the existing server instead of spawning its own.
+
+For remote GPU setups, add environment overrides (same pattern as the [watcher service](../guides/systemd-services.md#remote-gpu)):
+
+```ini
+Environment=CLAWMEM_EMBED_URL=http://gpu-host:8088
+Environment=CLAWMEM_LLM_URL=http://gpu-host:8089
+Environment=CLAWMEM_LLM_MODEL=qwen3
+Environment=CLAWMEM_RERANK_URL=http://gpu-host:8090
+```
+
+## CORS
+
+The server allows `localhost:*` origins for local frontend development.