@digitalforgestudios/openclaw-sulcus 3.11.1 → 4.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.
Files changed (4) hide show
  1. package/README.md +65 -69
  2. package/index.ts +611 -517
  3. package/openclaw.plugin.json +87 -22
  4. package/package.json +8 -3
package/README.md CHANGED
@@ -1,6 +1,19 @@
1
- # Sulcus Memory Plugin for OpenClaw
1
+ # openclaw-sulcus
2
2
 
3
- Thermodynamic memory backend for [OpenClaw](https://github.com/openclaw/openclaw). Replaces file-based memory with Sulcus's heat-driven decay, cross-agent sync, and programmable triggers.
3
+ Thermodynamic memory + Apache AGE knowledge graph for [OpenClaw](https://openclaw.ai) agents.
4
+
5
+ Sulcus is not a simple memory store. It's a cognitive memory system: every memory is scored, classified, graph-linked, and subject to decay. The SIU v2 pipeline processes every store automatically. A sleep-cycle curator keeps things clean. Reactive triggers fire on memory events.
6
+
7
+ ## What Sulcus Does
8
+
9
+ - **Apache AGE knowledge graph** — temporal graph over all memories; entities, relationships, and provenance tracked automatically
10
+ - **SIU v2 pipeline** — SIVU (utility scoring) → SICU (type classification) → SILU (entity extraction) → AGE graph update → trigger evaluation, fires on every `memory_store`
11
+ - **Interaction-based decay** — 3 modes: Time-only, Interaction-only, Hybrid (default). Memories decay based on access patterns, not just wall-clock time. High-utility memories resist decay.
12
+ - **Curator (sleep cycle)** — background process that reclassifies, consolidates, summarizes, and re-vectorizes memories. Keeps the graph clean without manual intervention.
13
+ - **Relevance-weighted recall** — `score = similarity × 0.7 + heat × 0.3`. Frequently-accessed memories surface faster.
14
+ - **Confidence levels + conflict detection** — memories carry a confidence level (`observed`, `inferred`, `asserted`); the system detects contradictory nodes automatically (v2.3.0+).
15
+ - **Reactive triggers** — rules that fire on `on_store`, `on_recall`, `on_boost`, `on_decay` events. Actions: notify, boost, pin, tag, deprecate, webhook, chain.
16
+ - **Cross-agent sync** — optional cloud sync via `serverUrl`/`apiKey`. Local-first by default.
4
17
 
5
18
  ## Install
6
19
 
@@ -10,7 +23,7 @@ openclaw plugin install @digitalforgestudios/openclaw-sulcus
10
23
 
11
24
  ## Configure
12
25
 
13
- After install, add your API key to the plugin config in `~/.openclaw/openclaw.json`:
26
+ Add to `~/.openclaw/openclaw.json`:
14
27
 
15
28
  ```json
16
29
  "openclaw-sulcus": {
@@ -23,87 +36,70 @@ After install, add your API key to the plugin config in `~/.openclaw/openclaw.js
23
36
  }
24
37
  ```
25
38
 
26
- Then restart: `openclaw gateway restart`
27
-
28
- **No API key?** The plugin starts without one — it logs a warning and disables itself. Add the key when you're ready and restart.
39
+ Restart: `openclaw gateway restart`
29
40
 
30
- **Get an API key:** Sign up at [sulcus.ca](https://sulcus.ca) → Dashboard → Account → API Keys.
41
+ **No API key?** Plugin starts in local-only mode (no cloud sync). Get a key at [sulcus.ca](https://sulcus.ca) → Dashboard → API Keys.
31
42
 
32
- ## Config Options
33
-
34
- | Option | Default | Description |
35
- |---|---|---|
36
- | `serverUrl` | `https://api.sulcus.ca` | Sulcus server URL |
37
- | `apiKey` | — | Sulcus API key (`sk-...`) |
38
- | `agentId` | — | Agent identifier for namespacing |
39
- | `namespace` | same as `agentId` | Memory namespace |
40
- | `autoRecall` | `true` | Inject relevant memories into context |
41
- | `autoCapture` | `true` | Auto-store important info from conversations |
42
- | `maxRecallResults` | `5` | Max memories injected per turn |
43
- | `minRecallScore` | `0.3` | Min relevance threshold (0–1) |
44
-
45
- ## Tools Provided
43
+ ## Tools
46
44
 
47
45
  | Tool | Description |
48
46
  |---|---|
49
- | `memory_search` | Semantic search with heat scores |
50
- | `memory_get` | Retrieve by UUID (auto-boosts on recall) |
51
- | `memory_store` | Store with auto-detected type |
52
- | `memory_forget` | Delete by ID |
47
+ | `memory_store` | Store a memory. SIU pipeline fires automatically: scored, classified, graph-linked. |
48
+ | `memory_recall` | Semantic search with relevance weighting (similarity × 0.7 + heat × 0.3). |
49
+ | `memory_status` | Backend status, namespace info, hot nodes, decay mode, curator state. |
50
+ | `memory_delete` | Delete a memory by ID. Optionally trains SIVU to reject similar content. |
51
+ | `consolidate` | Merge and prune cold memories below a heat threshold. |
52
+ | `export_markdown` | Export all memories in current namespace as a Markdown document. |
53
+ | `import_markdown` | Import memories from a Markdown document into current namespace. |
54
+ | `evaluate_triggers` | Evaluate reactive triggers against an event and context object. |
55
+ | `trigger_feedback` | Submit feedback to improve trigger accuracy and SITU scoring. |
53
56
 
54
- ## Hooks & Extended Tools
57
+ ## Memory Types & Decay
55
58
 
56
- All hooks and tools are **enabled by default**. Override in your `openclaw.json` plugin config:
59
+ Choose the right type — decay rates differ significantly:
57
60
 
58
- ```json
59
- "openclaw-sulcus": {
60
- "enabled": true,
61
- "config": {
62
- "apiKey": "sk-YOUR_KEY_HERE",
63
- "hooks": {
64
- "before_prompt_build": { "action": "inject_awareness", "enabled": true },
65
- "before_agent_start": { "action": "auto_recall", "enabled": true, "limit": 5, "minScore": 0.3 },
66
- "agent_end": { "action": "none", "enabled": true }
67
- },
68
- "tools": {
69
- "memory_recall": { "enabled": true },
70
- "memory_store": { "enabled": true },
71
- "memory_status": { "enabled": true },
72
- "consolidate": { "enabled": true },
73
- "export_markdown": { "enabled": true },
74
- "import_markdown": { "enabled": true },
75
- "evaluate_triggers": { "enabled": true }
76
- }
77
- }
78
- }
79
- ```
80
-
81
- | Hook | Default | Description |
61
+ | Type | Decay Rate | Use For |
82
62
  |---|---|---|
83
- | `before_prompt_build` | ON | Inject memory awareness context into prompts |
84
- | `before_agent_start` | ON | Auto-recall relevant memories each turn |
85
- | `agent_end` | ON | Post-turn processing |
63
+ | `episodic` | Fast | Events, sessions, one-off observations |
64
+ | `semantic` | Slow | Concepts, relationships, domain knowledge |
65
+ | `preference` | Slower | User preferences, opinions, style |
66
+ | `fact` | Slow | Stable factual knowledge |
67
+ | `procedural` | Slowest | How-tos, processes, workflows |
86
68
 
87
- | Extended Tool | Default | Description |
88
- |---|---|---|
89
- | `consolidate` | ON | Cluster and merge similar memories |
90
- | `export_markdown` | ON | Export memories as markdown |
91
- | `import_markdown` | ON | Import memories from markdown |
92
- | `evaluate_triggers` | ON | Run reactive trigger evaluations |
69
+ ## Configuration Reference
93
70
 
94
- ## Features
71
+ | Option | Default | Description |
72
+ |---|---|---|
73
+ | `serverUrl` | — | Sulcus cloud URL (e.g. `https://api.sulcus.ca`) |
74
+ | `apiKey` | — | Sulcus API key (`sk-...`) |
75
+ | `agentId` | — | Agent identifier for namespacing |
76
+ | `namespace` | same as `agentId` | Memory namespace |
77
+ | `autoRecall` | `false` | Inject relevant memories into context before each turn |
78
+ | `autoCapture` | `false` | Auto-store important info from conversations |
79
+ | `maxRecallResults` | `5` | Max memories injected on auto-recall |
80
+ | `minRecallScore` | `0.3` | Min relevance score for auto-recall (0–1) |
81
+ | `boostOnRecall` | `true` | Boost heat when a memory is recalled (spaced repetition) |
82
+ | `captureOnCompaction` | `true` | Preserve memories before context compaction |
83
+ | `captureOnReset` | `true` | Capture session summary on `/reset` |
84
+ | `trackSessions` | `false` | Record session start/end as episodic memories |
85
+ | `captureFromAssistant` | `false` | Also capture from assistant messages |
86
+ | `captureToolResults` | `false` | Capture significant tool results |
87
+ | `captureLlmInsights` | `false` | Capture assistant decisions/preferences |
88
+ | `maxCapturePerTurn` | `3` | Max auto-captures per agent turn |
89
+
90
+ ## Hooks
95
91
 
96
- - **Auto-recall** — relevant memories injected before each agent turn
97
- - **Auto-capture** — important info from conversations stored automatically
98
- - **Heat decay** — memories cool over time; frequently accessed ones stay hot
99
- - **Cross-agent sync** — all agents under a tenant share memories
100
- - **Triggers** — programmable rules that fire on memory events
92
+ | Hook | Default | Description |
93
+ |---|---|---|
94
+ | `before_prompt_build` | ON | Inject memory awareness context |
95
+ | `before_agent_start` | ON | Auto-recall relevant memories |
96
+ | `agent_end` | ON | Post-turn processing (capture, triggers) |
101
97
 
102
98
  ## Links
103
99
 
104
- - [Sulcus](https://sulcus.ca) — sign up, dashboard, docs
105
- - [Node SDK](https://www.npmjs.com/package/@digitalforgestudios/sulcus) — `@digitalforgestudios/sulcus`
106
- - [GitHub](https://github.com/digitalforgeca/sulcus) — source, issues, discussions
100
+ - [sulcus.ca](https://sulcus.ca) — sign up, dashboard, docs
101
+ - [npm](https://www.npmjs.com/package/@digitalforgestudios/openclaw-sulcus) — `@digitalforgestudios/openclaw-sulcus`
102
+ - [GitHub](https://github.com/digitalforgeca/sulcus) — source, issues
107
103
 
108
104
  ## License
109
105