heurchain 1.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.
@@ -0,0 +1,361 @@
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
+
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."
13
+ },
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"
25
+ ],
26
+ "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
+ },
32
+ "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."
36
+ }
37
+ },
38
+
39
+ "session_protocol": {
40
+ "description": "Every agent interaction is a session. Sessions enable context continuity across restarts. Always follow this sequence.",
41
+ "startup_sequence": [
42
+ {
43
+ "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
+ }
61
+ },
62
+ {
63
+ "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
+ }
75
+ },
76
+ {
77
+ "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'"
85
+ }
86
+ ],
87
+ "shutdown_sequence": [
88
+ {
89
+ "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."
93
+ },
94
+ {
95
+ "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
+ }
106
+ }
107
+ ]
108
+ },
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
+ }
265
+ },
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
+ }
322
+ },
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"
337
+ }
338
+ },
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"
360
+ }
361
+ }