heurchain 1.4.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENT_CONFIG.json CHANGED
@@ -1,361 +1,204 @@
1
1
  {
2
- "$schema": "heurchain-agent-config/2.0",
3
- "package": "HeurChain",
4
- "version": "2.0.0",
5
- "purpose": "Self-configuration manifest. An AI agent reads this file once at session start to understand how to use HeurChain for persistent memory, knowledge retrieval, and session continuity. Follow the session_protocol section in order.",
6
-
2
+ "$schema": "heurchain-agent-config/3.0",
3
+ "package": "heurchain",
4
+ "package_version": "2.0.0",
5
+ "broker_version": "0.6.1",
6
+ "purpose": "Self-configuration manifest for AI agents connecting to a self-hosted HeurChain broker (0.6.1). Read once at session start. The broker serves the same guidance live at GET / and the full API at GET /openapi.json.",
7
7
  "deployment": {
8
- "broker_url": "http://192.168.1.203:3012",
9
- "mcp_gateway": "http://192.168.1.203:80",
10
- "mcp_sse_endpoint": "http://192.168.1.203:80/sse",
11
- "health_endpoint": "http://192.168.1.203:3012/health",
12
- "note": "All endpoints require no authentication. Replace 192.168.1.203 with your deployment host if different."
8
+ "broker_url": "http://localhost:8080",
9
+ "note": "Replace with your broker's address. Ask the user for it if it is not configured. The broker is self-hosted: see https://github.com/peterjohannmedina/heurchain/blob/master/docs/install.md",
10
+ "health": "GET /health (public)",
11
+ "ready": "GET /ready (public; also checks Qdrant)"
13
12
  },
14
-
15
- "interface_selection": {
16
- "description": "Choose exactly one interface based on your client type. Do not mix both in the same agent.",
17
- "use_mcp_if": [
18
- "You are Claude Code or any MCP-compatible SSE client",
19
- "You can establish a persistent SSE connection to the gateway"
20
- ],
21
- "use_http_if": [
22
- "You are OpenClaw, Hermes, or any agent making direct HTTP calls",
23
- "You are ChatGPT or a GPT Action using the REST API",
24
- "You cannot maintain an SSE connection"
13
+ "authentication": {
14
+ "headers": {
15
+ "X-HeurChain-API-Key": "<api_key>",
16
+ "X-HeurChain-Tenant": "<tenant_id>"
17
+ },
18
+ "alternative": "Authorization: Bearer <api_key> together with X-HeurChain-Tenant",
19
+ "public_endpoints": [
20
+ "GET /",
21
+ "GET /health",
22
+ "GET /ready",
23
+ "GET /openapi.json",
24
+ "GET /ontology/capabilities"
25
25
  ],
26
+ "if_missing": "Use the client's secret store or ask the user to configure the connection. Never write keys into memories or logs.",
27
+ "provisioning": "An operator creates a tenant and key with POST /admin/tenants (admin basic auth)."
28
+ },
29
+ "interface_selection": {
26
30
  "mcp": {
27
- "transport": "SSE",
28
- "connect_to": "http://192.168.1.203:80/sse",
29
- "preferred_search_tool": "heurchain_search",
30
- "note": "heurchain_search uses BM25 ranking over 460+ keys. Prefer it over obsidian_search_notes for knowledge base queries."
31
+ "use_if": "Your client supports MCP over HTTP (Claude Code, Codex, Gemini CLI, Cursor and others).",
32
+ "streamable_http": "POST http://<broker>/mcp/sse (preferred; stateless, survives broker restarts)",
33
+ "legacy_sse": "GET /mcp/sse then POST /mcp/message (sessions are lost when the broker restarts)",
34
+ "headers": "Send both HeurChain headers on every request.",
35
+ "claude_code_example": "claude mcp add --transport http heurchain http://localhost:8080/mcp/sse --header \"X-HeurChain-API-Key: $KEY\" --header \"X-HeurChain-Tenant: $TENANT\""
31
36
  },
32
37
  "http": {
33
- "base_url": "http://192.168.1.203:3012",
34
- "content_type": "application/json",
35
- "method": "Use standard HTTP GET/POST. No auth headers required."
38
+ "use_if": "Your agent makes direct HTTP calls.",
39
+ "base_url": "http://localhost:8080",
40
+ "content_type": "application/json"
36
41
  }
37
42
  },
38
-
39
43
  "session_protocol": {
40
- "description": "Every agent interaction is a session. Sessions enable context continuity across restarts. Always follow this sequence.",
41
44
  "startup_sequence": [
42
45
  {
43
46
  "step": 1,
44
- "action": "start_session",
45
- "why": "Creates a session_id that namespaces all your working memory. Without this, your memory keys will collide with other agents.",
46
- "request": {
47
- "method": "POST",
48
- "path": "/session/start",
49
- "body": {
50
- "agent_name": "{your_agent_name}",
51
- "metadata": {
52
- "task": "{brief description of what you are doing}",
53
- "client": "{your client type, e.g. claude-code, openclaw, hermes}"
54
- }
55
- }
56
- },
57
- "response_fields": {
58
- "session_id": "Store this. Pass it to every /agent/store call.",
59
- "started_at": "ISO8601 timestamp"
60
- }
47
+ "action": "GET /memory/manifest (MCP: heurchain_manifest)",
48
+ "why": "See what is already stored before asking the user for anything."
61
49
  },
62
50
  {
63
51
  "step": 2,
64
- "action": "recall_prior_context",
65
- "why": "Restores what you knew from prior sessions. If you are a returning agent, this brings back your persistent knowledge and the last session's working memory.",
66
- "request": {
67
- "method": "GET",
68
- "path": "/agent/{your_agent_name}/recall"
69
- },
70
- "response_interpretation": {
71
- "session_id_null": "You are a new agent with no prior sessions. Proceed without context.",
72
- "working_empty_longterm_populated": "You have persistent knowledge but the working tier was cleared. Review longterm entries.",
73
- "both_populated": "Full context restore. Treat working[] as recent scratch notes, longterm[] as your durable knowledge base."
74
- }
52
+ "action": "POST /session/start {agent_id} (MCP: heurchain_session_start)",
53
+ "why": "Returns session_id; pass it as metadata.session_id on every store this conversation."
75
54
  },
76
55
  {
77
56
  "step": 3,
78
- "action": "check_health",
79
- "why": "Verify all storage backends are available before starting work.",
80
- "request": {
81
- "method": "GET",
82
- "path": "/health"
83
- },
84
- "abort_if": "status is not 'ok' or backends.redis.status is not 'connected'"
57
+ "action": "GET /agent/{agent_id} (MCP: heurchain_agent_recall)",
58
+ "why": "Recall your own recent memories."
85
59
  }
86
60
  ],
61
+ "during_work": [
62
+ "Store durable facts, decisions and outcomes with POST /store (MCP: heurchain_store). Use a stable id for retries.",
63
+ "Search before asking: POST /search (hybrid BM25 + dense, RRF) or POST /query (dense similarity).",
64
+ "Before compaction or a long handoff: POST /memory/checkpoint, then POST /memory/resume by checkpoint_id later."
65
+ ],
87
66
  "shutdown_sequence": [
88
67
  {
89
68
  "step": 1,
90
- "action": "persist_important_findings",
91
- "why": "Working-tier memory is not permanent. Anything you want in the next session must be explicitly persisted.",
92
- "how": "Call POST /agent/store with persist=true for any key facts, conclusions, or artifacts produced this session."
69
+ "action": "POST /session/end {session_id} (MCP: heurchain_session_end)"
93
70
  },
94
71
  {
95
72
  "step": 2,
96
- "action": "end_session",
97
- "why": "Marks the session as ended and attaches a summary. The summary is searchable in future sessions.",
98
- "request": {
99
- "method": "POST",
100
- "path": "/session/end",
101
- "body": {
102
- "session_id": "{session_id from startup}",
103
- "summary": "{1-3 sentence summary of what was accomplished and what to pick up next time}"
104
- }
105
- }
73
+ "action": "Store a concise session summary with POST /store"
106
74
  }
107
75
  ]
108
76
  },
109
-
110
- "key_schema": {
111
- "description": "HeurChain uses a colon-separated key namespace. Keys determine which storage tier is used (via 'auto' tier routing). Always namespace your agent-specific keys with your agent_name to prevent collisions.",
112
- "patterns": {
113
- "agent_session_working": "memory:agent:{agent_name}:{session_id}:{descriptor}",
114
- "agent_persistent": "doc:agent:{agent_name}:{descriptor}",
115
- "shared_knowledge": "doc:{domain}:{topic}",
116
- "shared_working": "memory:{topic}:{descriptor}",
117
- "session_metadata": "session:{session_id}",
118
- "agent_session_registry": "agent:{agent_name}:sessions"
119
- },
120
- "examples": {
121
- "agent_session_working": "memory:agent:claude-code:claude-code-20260501T184608Z-7507bae9:task_notes",
122
- "agent_persistent": "doc:agent:hermes:embedding_strategy",
123
- "shared_knowledge": "doc:proxmox:cluster-status",
124
- "shared_working": "memory:openclaw:active_conversation"
125
- },
126
- "auto_tier_routing": {
127
- "rule": "When tier='auto', the prefix determines the tier.",
128
- "memory_prefix": "working tier (Ori vault markdown)",
129
- "doc_prefix": "longterm tier (Redis + Obsidian vault mirror)",
130
- "knowledge_prefix": "longterm tier",
131
- "session_prefix": "longterm tier",
132
- "everything_else": "longterm tier (default)"
133
- },
134
- "collision_prevention": "Always include your agent_name in keys you own. Never write to doc:agent:{other_agent_name}:* keys. Shared keys (doc:proxmox:*, knowledge:*) are readable by all agents but write with care — coordinate with other agents before overwriting shared knowledge."
135
- },
136
-
137
- "operations": {
138
- "store_working_memory": {
139
- "description": "Store a temporary note scoped to your current session. Cleared when Ori vault is pruned by the consolidation worker (default: 7 days).",
140
- "method": "POST",
141
- "path": "/agent/store",
142
- "body": {
143
- "agent_name": "{your_agent_name}",
144
- "session_id": "{session_id}",
145
- "key": "{short_descriptor}",
146
- "content": "{markdown content}",
147
- "tags": ["optional", "tags"],
148
- "persist": false
149
- },
150
- "resulting_key": "memory:agent:{agent_name}:{session_id}:{key}",
151
- "use_for": ["in-progress task notes", "intermediate results", "scratch calculations", "conversation context"]
152
- },
153
- "store_persistent_memory": {
154
- "description": "Store something that must survive session end. Writes to both working tier AND longterm Redis.",
155
- "method": "POST",
156
- "path": "/agent/store",
157
- "body": {
158
- "agent_name": "{your_agent_name}",
159
- "session_id": "{session_id}",
160
- "key": "{descriptor}",
161
- "content": "{markdown content}",
162
- "persist": true
163
- },
164
- "resulting_keys": {
165
- "working": "memory:agent:{agent_name}:{session_id}:{key}",
166
- "longterm": "doc:agent:{agent_name}:{key}"
167
- },
168
- "use_for": ["key findings", "decisions made", "artifacts produced", "facts learned that apply to future sessions"]
169
- },
170
- "store_shared_knowledge": {
171
- "description": "Write to the shared knowledge base. All agents can read this. Use for infrastructure docs, system state, runbooks.",
172
- "method": "POST",
173
- "path": "/store",
174
- "body": {
175
- "key": "doc:{domain}:{topic}",
176
- "content": "{markdown content}",
177
- "tags": ["optional"],
178
- "tier": "longterm",
179
- "source": "{your_agent_name}"
180
- }
181
- },
182
- "search": {
183
- "description": "BM25 ranked search across all indexed documents (460+ Redis keys + Ori vault files). Use this before answering any question that may already be in the knowledge base.",
184
- "method": "GET",
185
- "path": "/search",
186
- "params": {
187
- "q": "your natural language query",
188
- "limit": "10 (default) — increase to 25-50 for broad queries",
189
- "tier": "all | longterm | working (default: all)"
190
- },
191
- "response_fields": {
192
- "key": "storage key",
193
- "score": "BM25 relevance score (higher = more relevant)",
194
- "content": "full document content",
195
- "tier": "longterm or working",
196
- "updated_at": "ISO8601 last-write timestamp"
197
- },
198
- "guidance": "Score > 2.0 is a strong match. Score < 0.5 is likely noise. If no results, try shorter query terms or fewer words."
199
- },
200
- "get_by_key": {
201
- "description": "Retrieve a specific document by exact key. Returns the most recently written copy if the key exists in both tiers.",
202
- "method": "GET",
203
- "path": "/get",
204
- "params": {
205
- "key": "exact key string",
206
- "tier": "all | longterm | working (default: all)"
207
- }
208
- },
209
- "recall_session": {
210
- "description": "Restore the full context of a previous session. Use at startup (step 2 above). Can also be called mid-session to restore a specific earlier session.",
211
- "method": "GET",
212
- "path": "/agent/{agent_name}/recall",
213
- "optional_params": {
214
- "session_id": "Omit to get most recent session. Provide to restore a specific session."
215
- },
216
- "response_fields": {
217
- "session_id": "The session being restored",
218
- "agent_name": "Confirmed agent name",
219
- "session_meta": "Session metadata including summary if set",
220
- "working": "Array of working-tier entries from this session",
221
- "longterm": "Array of longterm entries for this agent"
222
- }
223
- },
224
- "list_sessions": {
225
- "description": "List all past sessions for your agent, newest first. Useful for reviewing session history.",
226
- "method": "GET",
227
- "path": "/agent/{agent_name}/sessions"
228
- },
229
- "get_session_context": {
230
- "description": "Get full memory for a specific session by ID.",
231
- "method": "GET",
232
- "path": "/session/{session_id}/context"
233
- },
234
- "promote_to_longterm": {
235
- "description": "Explicitly promote a working-tier entry to longterm Redis. Useful when you decide mid-session that a scratch note should be permanent.",
236
- "method": "POST",
237
- "path": "/promote",
238
- "params": {
239
- "key": "exact working-tier key to promote",
240
- "new_key": "(optional) rename the key in longterm"
241
- }
242
- }
243
- },
244
-
245
- "mcp_tools": {
246
- "description": "If using the MCP interface, these are the available tools. Prefer heurchain_search over obsidian_search_notes — it uses BM25 ranking over the full Redis keyspace.",
247
- "memory": {
248
- "cache_set": "Write a key-value pair directly to Redis. No tier routing. For simple ephemeral cache entries.",
249
- "cache_get": "Read a Redis key directly.",
250
- "cache_delete": "Delete a Redis key."
251
- },
252
- "search": {
253
- "heurchain_search": "BM25 ranked search via the broker. Params: query, limit (default 10), tier (all/longterm/working). PREFERRED for knowledge base queries.",
254
- "obsidian_search_notes": "Naive substring search across vault markdown files. Use only as fallback."
255
- },
256
- "vault": {
257
- "obsidian_write_note": "Write a markdown note to the Obsidian vault. Params: key, content, metadata.",
258
- "obsidian_read_note": "Read a vault note by key.",
259
- "obsidian_delete_note": "Delete a vault note.",
260
- "obsidian_list_notes": "List vault notes, optionally filtered by prefix."
261
- },
262
- "health": {
263
- "health_check": "Returns status of Redis, Ori vault, and Obsidian vault backends."
264
- }
77
+ "namespaces": {
78
+ "ops": "fastest decay: transient operational detail",
79
+ "notes": "default: ordinary working memory",
80
+ "self": "slowest decay: durable facts you want kept",
81
+ "note": "Decayed memories move to the vault: preserved, but no longer returned by /search or /query. Unknown values return 400."
265
82
  },
266
-
267
- "behavioral_guidance": {
268
- "description": "Decision rules for when and what to store. Follow these to be a well-behaved HeurChain agent.",
269
- "rules": [
270
- {
271
- "trigger": "At session start, always",
272
- "action": "Run the 3-step startup_sequence. Never skip /agent/recall — you may be returning to an in-progress task.",
273
- "priority": "mandatory"
274
- },
275
- {
276
- "trigger": "Before answering any question about the infrastructure, codebase, or domain",
277
- "action": "Call /search?q={topic} first. If score > 1.5, use that context in your answer. Do not hallucinate facts that may already be in the knowledge base.",
278
- "priority": "mandatory"
279
- },
280
- {
281
- "trigger": "You learn a fact that is broadly reusable (IP address, architecture decision, system state)",
282
- "action": "Store to doc:{domain}:{topic} with tier=longterm. Tag with source={your_agent_name}.",
283
- "priority": "recommended"
284
- },
285
- {
286
- "trigger": "You are mid-task and produce an intermediate result or plan",
287
- "action": "Store to working memory via /agent/store with persist=false. This lets you resume if interrupted.",
288
- "priority": "recommended"
289
- },
290
- {
291
- "trigger": "Task is complete and you produced a deliverable (code, config, document)",
292
- "action": "Store the outcome with persist=true before session end so the next session can see it.",
293
- "priority": "recommended"
294
- },
295
- {
296
- "trigger": "At session end, always",
297
- "action": "Call /session/end with a summary. Even one sentence. This summary is searchable in future sessions.",
298
- "priority": "mandatory"
299
- },
300
- {
301
- "trigger": "You are about to write a key that already exists",
302
- "action": "Call /get first. If the existing content is newer or more accurate, merge or append rather than overwrite.",
303
- "priority": "recommended"
304
- },
305
- {
306
- "trigger": "Your task is specific to your agent and should not be visible to other agents",
307
- "action": "Use doc:agent:{your_name}:{key} or memory:agent:{your_name}:{session_id}:{key} patterns exclusively.",
308
- "priority": "mandatory"
309
- }
310
- ],
311
- "agent_naming": {
312
- "description": "Choose a stable, unique agent_name. This name persists across all your sessions.",
313
- "convention": "Use lowercase hyphen-separated identifiers that reflect your role.",
314
- "examples": {
315
- "claude-code": "Claude Code running in a developer session",
316
- "openclaw-agent": "An OpenClaw framework agent",
317
- "hermes": "The Hermes/Ori-Mnemos embedding agent on VM 104",
318
- "chatgpt-actions": "ChatGPT GPT Actions integration"
319
- },
320
- "warning": "Two agents with the same name share session history. Only use the same name if you intend continuity (e.g., always 'claude-code' for all Claude Code sessions)."
321
- }
83
+ "store_result": {
84
+ "200_indexed_true": "Stored and indexed.",
85
+ "202_indexed_false": "Stored durably but indexing is incomplete (embedder or Qdrant unavailable). Retry with the same id; there is no background retry queue."
322
86
  },
323
-
324
- "tier_reference": {
325
- "working": {
326
- "storage": "Ori vault (markdown files with YAML frontmatter)",
327
- "path": "/mnt/pvet630/openclaw/ori-vault/notes/ (Ansible) or ./data/ori-vault/notes/ (Docker)",
328
- "persistence": "7 days default (consolidation_worker promotes aged notes to longterm automatically)",
329
- "indexed_by": "Keyword search (Ori vault scan), not BM25",
330
- "best_for": "Session-scoped scratch space, in-progress notes, short-lived context"
331
- },
332
- "longterm": {
333
- "storage": "Redis keyspace + Obsidian vault markdown mirror",
334
- "persistence": "Indefinite (no TTL unless you set one explicitly with /store + redis TTL)",
335
- "indexed_by": "BM25 in-memory index (rebuilt on startup, updated on every /store)",
336
- "best_for": "Durable knowledge base, reference documents, agent learning"
87
+ "tips": [
88
+ "Put absolute dates in stored text (e.g. '2026-11-01: ...'); relative phrases like 'last Saturday' cannot be resolved later.",
89
+ "For multi-hop or conversational recall, request more results (limit 25-30) before anything more elaborate.",
90
+ "Keep secrets and private reasoning out of memories; store references to where a secret lives instead."
91
+ ],
92
+ "http_operations": {
93
+ "POST /admin/vault/rehydrate": {
94
+ "summary": "Restore one vaulted document to active retrieval",
95
+ "auth": "admin basic auth"
96
+ },
97
+ "GET /agent/{agent_id}": {
98
+ "summary": "Get an agent's most recent memories",
99
+ "auth": "tenant API key"
100
+ },
101
+ "GET /agent/{agent_id}/recall": {
102
+ "summary": "Get active session IDs for compatibility",
103
+ "auth": "tenant API key"
104
+ },
105
+ "POST /graph/ask": {
106
+ "summary": "Bounded multi-hop knowledge-graph retrieval",
107
+ "auth": "tenant API key"
108
+ },
109
+ "GET /health": {
110
+ "summary": "Check Redis/SQLite liveness; does not check Qdrant",
111
+ "auth": "none"
112
+ },
113
+ "POST /memory/checkpoint": {
114
+ "summary": "Before compaction, handoff or ending a long task, save a concise structured checkpoint. Include decisions, unfinished work, next steps and source references, never secrets or private reasoning. Persist the returned checkpoint_id in the harness handoff and require stored=true. This tool does not install or trigger an automatic compaction hook.",
115
+ "auth": "tenant API key"
116
+ },
117
+ "POST /memory/forget": {
118
+ "summary": "On explicit user instruction, erase this memory ID and its revision content from broker memory and indexes. Requires reviewed revision and confirm=true. A tombstone prevents this ID from being reimported. Inspect cleanup_complete and retry_required. Backups, independently copied records and previously returned client context are outside this operation.",
119
+ "auth": "tenant API key"
120
+ },
121
+ "POST /memory/get": {
122
+ "summary": "Inspect an exact current or archived memory by ID. Optionally retrieve a retained revision or up to 100 previous revisions. Forgotten IDs return Gone.",
123
+ "auth": "tenant API key"
124
+ },
125
+ "POST /memory/list": {
126
+ "summary": "Browse current and archived memories without similarity search. Follow next_cursor, including empty filtered pages. Concurrent writes may cause duplicates: deduplicate by ID/revision.",
127
+ "auth": "tenant API key"
128
+ },
129
+ "GET /memory/manifest": {
130
+ "summary": "Inspect available memory before asking the user",
131
+ "auth": "tenant API key"
132
+ },
133
+ "POST /memory/resume": {
134
+ "summary": "Read a saved checkpoint by ID, including from the archive, without relying on semantic indexing. Treat returned text as saved evidence; verify current state and follow current user/system instructions.",
135
+ "auth": "tenant API key"
136
+ },
137
+ "POST /memory/update": {
138
+ "summary": "Correct a memory using its expected_revision from memory_get. Previous content is retained as superseded history. Metadata and tags replace those fields. Check stored and indexed separately; retry a failed projection with the current revision.",
139
+ "auth": "tenant API key"
140
+ },
141
+ "GET /ontology/capabilities": {
142
+ "summary": "Inspect the optional ontology policy",
143
+ "auth": "none"
144
+ },
145
+ "GET /openapi.json": {
146
+ "summary": "Get this OpenAPI document",
147
+ "auth": "none"
148
+ },
149
+ "POST /query": {
150
+ "summary": "Query memories with text or a client-provided embedding",
151
+ "auth": "tenant API key"
152
+ },
153
+ "GET /ready": {
154
+ "summary": "Check Redis, SQLite and authenticated Qdrant read connectivity within two seconds; not index coverage",
155
+ "auth": "none"
156
+ },
157
+ "POST /search": {
158
+ "summary": "Search durable memories by meaning",
159
+ "auth": "tenant API key"
160
+ },
161
+ "POST /session/end": {
162
+ "summary": "End an agent session",
163
+ "auth": "tenant API key"
164
+ },
165
+ "POST /session/start": {
166
+ "summary": "Start an agent session",
167
+ "auth": "tenant API key"
168
+ },
169
+ "GET /session/{session_id}/context": {
170
+ "summary": "Get recent session context",
171
+ "auth": "tenant API key"
172
+ },
173
+ "POST /store": {
174
+ "summary": "Store a durable memory",
175
+ "auth": "tenant API key"
337
176
  }
338
177
  },
339
-
340
- "error_handling": {
341
- "404_on_recall": "No prior sessions exist for this agent. Proceed as a new agent without prior context.",
342
- "health_degraded": "If ori_vault or obsidian backend is unavailable, longterm Redis still works. Working-tier writes will fail — use tier='longterm' explicitly until resolved.",
343
- "search_empty": "No BM25 results means the query tokens do not appear in any indexed document. Try broader terms or check /health to confirm Redis is connected.",
344
- "session_not_found": "session_id is invalid or expired. Start a new session. Prior working memory for that session may be unrecoverable.",
345
- "500_on_store": "Check /health. Most 500s on /store are Redis connectivity failures or Ori vault path permission errors."
346
- },
347
-
348
- "quick_reference": {
349
- "start_session": "POST /session/start {agent_name, metadata}",
350
- "recall_context": "GET /agent/{name}/recall",
351
- "store_working": "POST /agent/store {agent_name, session_id, key, content, persist:false}",
352
- "store_persistent": "POST /agent/store {agent_name, session_id, key, content, persist:true}",
353
- "search_knowledge": "GET /search?q=&limit=&tier=",
354
- "get_by_key": "GET /get?key=",
355
- "end_session": "POST /session/end {session_id, summary}",
356
- "list_sessions": "GET /agent/{name}/sessions",
357
- "restore_old_session": "GET /agent/{name}/recall?session_id=",
358
- "promote_to_longterm": "POST /promote?key=",
359
- "health": "GET /health"
178
+ "mcp_tools": {
179
+ "heurchain_store": "Store a fact, decision or concise summary. Store secret references, never passwords, tokens or private reasoning. Supply a stable ID for retries; use memory_update with expected_revision for corrections.",
180
+ "heurchain_search": "Hybrid BM25 + dense vector search. Best for keyword lookups — project names, credential labels, specific identifiers.",
181
+ "heurchain_query": "Semantic similarity search. Best for natural-language retrieval ('what did I decide about authentication?').",
182
+ "heurchain_promote": "Increment a memory item's retrieval weight. Call after a human confirms a stored fact is correct.",
183
+ "heurchain_manifest": "Get a memory summary: total count, per-tag counts, per-agent counts, 10 most-recent items. Call at task start before asking for things already stored.",
184
+ "heurchain_session_start": "Open a session to correlate all store calls in this conversation. Returns a session_id — pass it in metadata.session_id on every store call.",
185
+ "heurchain_session_end": "Close a session. Call at conversation end, then store a session summary tagged 'conversation'.",
186
+ "heurchain_session_context": "Replay a prior session: returns items written under that session_id, ordered by recency. Use to resume a conversation without re-querying the user.",
187
+ "heurchain_agent_recall": "List session IDs for an agent. Use at session start to discover prior sessions, then call session_context on each.",
188
+ "heurchain_memory_history": "Audit trail for a single memory item: the rows in this tenant's audit log whose resource is this id, newest first, capped at the 100 most recent. In practice these are store and lifecycle events (the writes that stamped resource=<id>), not reads — a query that happened to retrieve this item is not recorded against it, so an empty result does not mean the item was never retrieved.",
189
+ "heurchain_embed": "Embed text into a dense vector using the server's active embedding model. Use to pre-compute an embedding for query, or to inspect dimensionality.",
190
+ "heurchain_agents": "List agent_ids active in this tenant over the last 7 days, with last-seen time and event counts. Use to discover which agents have been writing memory.",
191
+ "heurchain_vault_stats": "Storage stats for this tenant: vector count, total bytes, size in MB, estimated token count.",
192
+ "heurchain_vault_flush": "Flush working memory: consolidate hot vectors into the durable vault for this tenant. Call at the end of a long session to persist accumulated memories.",
193
+ "heurchain_vault_export": "Export this tenant's stored memories as a zip archive of human-readable Markdown files (embeddings excluded). Use for backup or audit.",
194
+ "heurchain_cache_set": "Store a short-lived key-value pair in the tenant cache (Redis, TTL-backed). For ephemeral state: current session_id, active model, in-progress task ID.",
195
+ "heurchain_cache_get": "Retrieve a value from the tenant cache. Returns {found: false} if absent or expired.",
196
+ "heurchain_cache_delete": "Delete a key from the tenant cache.",
197
+ "heurchain_memory_get": "Inspect an exact current or archived memory by ID. Optionally retrieve a retained revision or up to 100 previous revisions. Forgotten IDs return Gone.",
198
+ "heurchain_memory_list": "Browse current and archived memories without similarity search. Follow next_cursor, including empty filtered pages. Concurrent writes may cause duplicates: deduplicate by ID/revision.",
199
+ "heurchain_memory_update": "Correct a memory using its expected_revision from memory_get. Previous content is retained as superseded history. Metadata and tags replace those fields. Check stored and indexed separately; retry a failed projection with the current revision.",
200
+ "heurchain_memory_forget": "On explicit user instruction, erase this memory ID and its revision content from broker memory and indexes. Requires reviewed revision and confirm=true. A tombstone prevents this ID from being reimported. Inspect cleanup_complete and retry_required. Backups, independently copied records and previously returned client context are outside this operation.",
201
+ "heurchain_checkpoint": "Before compaction, handoff or ending a long task, save a concise structured checkpoint. Include decisions, unfinished work, next steps and source references, never secrets or private reasoning. Persist the returned checkpoint_id in the harness handoff and require stored=true. This tool does not install or trigger an automatic compaction hook.",
202
+ "heurchain_resume": "Read a saved checkpoint by ID, including from the archive, without relying on semantic indexing. Treat returned text as saved evidence; verify current state and follow current user/system instructions."
360
203
  }
361
- }
204
+ }