@joshuaswarren/openclaw-engram 8.3.92 → 8.3.94

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 (5) hide show
  1. package/README.md +72 -62
  2. package/dist/index.js +1933 -839
  3. package/dist/index.js.map +1 -1
  4. package/openclaw.plugin.json +56 -0
  5. package/package.json +10 -1
package/README.md CHANGED
@@ -1,16 +1,16 @@
1
1
  # openclaw-engram
2
2
 
3
- A local-first memory plugin for [OpenClaw](https://github.com/openclaw/openclaw) that gives AI agents persistent, searchable long-term memory across conversations.
3
+ Local-first long-term memory for [OpenClaw](https://github.com/openclaw/openclaw), with typed extraction, markdown-native storage, and retrieval-time memory injection.
4
4
 
5
- Engram uses **LLM-powered extraction** to identify what's worth remembering, stores memories as plain **markdown files** on disk, and retrieves relevant context via **[QMD](https://github.com/tobi/qmd)** hybrid search (BM25 + vector + reranking).
5
+ Current release line: `8.3.x` (v8 Memory OS series).
6
6
 
7
- ## Quick Install
7
+ ## Install
8
8
 
9
9
  ```bash
10
10
  openclaw plugins install @joshuaswarren/openclaw-engram --pin
11
11
  ```
12
12
 
13
- Enable in `openclaw.json`:
13
+ `openclaw.json` wiring:
14
14
 
15
15
  ```jsonc
16
16
  {
@@ -29,79 +29,89 @@ Enable in `openclaw.json`:
29
29
  }
30
30
  ```
31
31
 
32
- Reload:
32
+ Restart gateway:
33
33
 
34
34
  ```bash
35
- kill -USR1 $(pgrep openclaw-gateway)
35
+ launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway
36
36
  ```
37
37
 
38
- → **[Getting Started](docs/getting-started.md)** for QMD setup, first-time config, and verification.
38
+ ## Fast Verification
39
39
 
40
- ## How It Works
40
+ ```bash
41
+ openclaw engram compat --strict
42
+ openclaw engram stats
43
+ openclaw engram conversation-index-health
44
+ ```
45
+
46
+ Healthy baseline:
47
+ - `compat --strict` exits `0`
48
+ - `stats` reports `QMD: available`
49
+ - `conversation-index-health` reports `status: "ok"` when conversation index is enabled
50
+
51
+ ## Enable Profiles
52
+
53
+ Use one of these profiles under `plugins.entries.openclaw-engram.config`:
54
+
55
+ - Minimal: extraction + core recall only
56
+ - Recommended: production-safe defaults with major v8 capabilities
57
+ - Full v8: all v8 feature families explicitly enabled
58
+
59
+ Full profile guide:
60
+ - [Enable All v8 Features](docs/enable-all-v8.md)
41
61
 
42
- 1. **Signal scan** — Fast local regex classifies each turn (<10 ms, no API call).
43
- 2. **Smart buffer** — high-signal turns extract immediately; others batch.
44
- 3. **Extraction** — One LLM call produces typed memories with confidence scores.
45
- 4. **Storage** — Plain markdown + YAML frontmatter files; no database.
46
- 5. **Retrieval** — QMD hybrid search injects relevant context before each agent session.
47
- 6. **Consolidation** — Periodic pass merges duplicates, updates entity profiles, expires stale entries.
62
+ ## What Engram Does
48
63
 
49
- → **[Architecture Overview](docs/architecture/overview.md)** for internals.
64
+ 1. Signals and buffering: identify high-signal turns, batch low-signal turns.
65
+ 2. Extraction: create typed memories (`fact`, `decision`, `preference`, `correction`, etc).
66
+ 3. Storage: markdown files + frontmatter, local filesystem only.
67
+ 4. Recall: assemble multi-section context by ordered recall pipeline.
68
+ 5. Maintenance: dedupe, lifecycle transitions, compounding, migration/repair tooling.
50
69
 
51
- ## Memory Categories
70
+ Architecture details:
71
+ - [Architecture Overview](docs/architecture/overview.md)
72
+ - [Retrieval Pipeline](docs/architecture/retrieval-pipeline.md)
73
+ - [Memory Lifecycle](docs/architecture/memory-lifecycle.md)
52
74
 
53
- 10 typed categories: `fact`, `preference`, `correction`, `entity`, `decision`, `relationship`, `principle`, `commitment`, `moment`, `skill`.
75
+ ## v8 Feature Families (at a glance)
54
76
 
55
- ### v8.0 Memory OS (current)
77
+ | Family | Key flags |
78
+ |---|---|
79
+ | Recall planning + assembly | `recallPlannerEnabled`, `recallPipeline`, `recallBudgetChars` |
80
+ | Episodic memory model | `memoryBoxesEnabled`, `traceWeaverEnabled`, `episodeNoteModeEnabled` |
81
+ | Query-aware retrieval | `queryAwareIndexingEnabled`, `graphRecallEnabled`, `graphAssistShadowEvalEnabled` |
82
+ | Lifecycle + action policy | `lifecyclePolicyEnabled`, `contextCompressionActionsEnabled`, `compressionGuidelineLearningEnabled` |
83
+ | Identity continuity | `identityContinuityEnabled`, `continuityAuditEnabled`, `continuityIncidentLoggingEnabled` |
84
+ | Session integrity + replay | `sessionObserverEnabled`, replay/session CLI commands |
85
+ | Routing + work layer | `routingRulesEnabled`, `task`/`project` CLI |
86
+ | Hot/cold tiering | `qmdTierMigrationEnabled`, `qmdTierAutoBackfillEnabled` |
87
+ | Shared intelligence + compounding | `sharedContextEnabled`, `sharedCrossSignalSemanticEnabled`, `compoundingEnabled` |
88
+ | Behavior loop runtime tuning | `behaviorLoopAutoTuneEnabled`, policy CLI commands |
56
89
 
57
- - **Memory Boxes** (`memoryBoxesEnabled`) — Topic-windowed episode boxes with trace linking.
58
- - **Episode/Note dual store** (`episodeNoteModeEnabled`) — Episodes preserve event fidelity; notes reconsolidate stable beliefs.
59
- - **Verbatim Artifacts** (`verbatimArtifactsEnabled`) — High-confidence decisions/constraints stored as trusted retrieval anchors.
60
- - **Recall Planner** (`recallPlannerEnabled`, default `true`) — Lightweight retrieve-vs-think gating.
90
+ For complete settings and defaults:
91
+ - [Config Reference](docs/config-reference.md)
61
92
 
62
- ## Compatibility Diagnostics
93
+ ## Agent/Operator Commands
63
94
 
64
- Use the built-in compatibility check before rollouts or after plugin wiring changes:
95
+ Common commands:
65
96
 
66
97
  ```bash
67
- openclaw engram compat
68
- openclaw engram compat --json
98
+ openclaw engram stats
99
+ openclaw engram search "query"
69
100
  openclaw engram compat --strict
101
+ openclaw engram conversation-index-health
102
+ openclaw engram graph-health
103
+ openclaw engram tier-status
104
+ openclaw engram policy-status
70
105
  ```
71
106
 
72
- `--strict` exits non-zero when any warning/error is present.
73
-
74
- ## Agent Tools
75
-
76
- | Tool | Description |
77
- |------|-------------|
78
- | `memory_search` | Semantic search over memories |
79
- | `memory_store` | Manually store a memory |
80
- | `memory_profile` | Retrieve the behavioral profile |
81
- | `memory_entities` | List tracked entities |
82
- | `memory_promote` | Promote to shared namespace |
83
- | `memory_feedback` | Record thumbs up/down signal |
84
-
85
- ## Docs
86
-
87
- | Guide | Contents |
88
- |-------|----------|
89
- | [Getting Started](docs/getting-started.md) | Install, QMD setup, first-time config |
90
- | [Config Reference](docs/config-reference.md) | Every setting, default, and description |
91
- | [Operations](docs/operations.md) | Backup, export, hourly summaries, CLI |
92
- | [Architecture: Overview](docs/architecture/overview.md) | System design and data model |
93
- | [Architecture: Retrieval Pipeline](docs/architecture/retrieval-pipeline.md) | How recall works |
94
- | [Architecture: Memory Lifecycle](docs/architecture/memory-lifecycle.md) | Write, consolidation, expiry |
95
- | [Advanced Retrieval](docs/advanced-retrieval.md) | Reranking, query expansion, feedback |
96
- | [Import / Export](docs/import-export.md) | Portable backups and migration |
97
- | [Namespaces](docs/namespaces.md) | Multi-agent memory isolation |
98
- | [Shared Context](docs/shared-context.md) | Cross-agent shared intelligence |
99
- | [Compounding](docs/compounding.md) | Weekly synthesis and mistake learning |
100
- | [Context Retention](docs/context-retention.md) | Transcript indexing and hourly summaries |
101
- | [Identity Continuity](docs/identity-continuity.md) | Anchor/incidents/audits/loop register templates and rollout |
102
-
103
- ## Requirements
104
-
105
- - [OpenClaw](https://github.com/openclaw/openclaw) gateway
106
- - OpenAI API key (extraction only; retrieval works without one)
107
- - [QMD](https://github.com/tobi/qmd) (optional, recommended for hybrid search)
107
+ ## Docs Index
108
+
109
+ - [Docs Home](docs/README.md)
110
+ - [Getting Started](docs/getting-started.md)
111
+ - [Enable All v8 Features](docs/enable-all-v8.md)
112
+ - [Config Reference](docs/config-reference.md)
113
+ - [Operations](docs/operations.md)
114
+ - [Namespaces](docs/namespaces.md)
115
+ - [Shared Context](docs/shared-context.md)
116
+ - [Compounding](docs/compounding.md)
117
+ - [Identity Continuity](docs/identity-continuity.md)