{"_id":"@artale/openclaw-memory","_rev":"3-a65b2e4b1649d20498323a07264b6a96","name":"@artale/openclaw-memory","dist-tags":{"latest":"2.0.1"},"versions":{"1.0.0":{"name":"@artale/openclaw-memory","version":"1.0.0","keywords":["openclaw","memory","hindsight","alma","observational-memory","agent"],"author":{"name":"Artale","email":"arosstale1@gmail.com"},"license":"MIT","_id":"@artale/openclaw-memory@1.0.0","maintainers":[{"name":"artale","email":"arosstale1@gmail.com"}],"homepage":"https://github.com/arosstale/openclaw-memory#readme","bugs":{"url":"https://github.com/arosstale/openclaw-memory/issues"},"dist":{"shasum":"dbf706119608445457e7268120c524bce90e4c96","tarball":"https://registry.npmjs.org/@artale/openclaw-memory/-/openclaw-memory-1.0.0.tgz","fileCount":56,"integrity":"sha512-bTRBA+Wnh2eKTzWTIzxnEhcyFP4XBNGa6gna8zdtp2mA8tStRmZapuUdbuNJSm3YwiRgUZYqa4RbqDlJcptpDQ==","signatures":[{"sig":"MEUCIEL1cVIWY0L39GRJD84FgcoiXz/a3e5SCm0pgmPUiI9VAiEApidgTrXaWh4flYhhOI3/3e8ULwWz2ZHrfH8+VJvD8vA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":140734},"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./alma":{"types":"./dist/alma/ALMAAgent.d.ts","import":"./dist/alma/ALMAAgent.js"},"./hooks":{"types":"./dist/middleware/hooks.d.ts","import":"./dist/middleware/hooks.js"},"./memory":{"types":"./dist/observational-memory/ObserverAgent.d.ts","import":"./dist/observational-memory/ObserverAgent.js"},"./search":{"types":"./dist/knowledge/MemoryIndexer.d.ts","import":"./dist/knowledge/MemoryIndexer.js"},"./dashboard":{"types":"./dist/dashboard/server.d.ts","import":"./dist/dashboard/server.js"}},"gitHead":"7f54ad7519449215917f9f6003d54932327f1260","scripts":{"dev":"tsc --watch","lint":"eslint src","test":"vitest","build":"tsc","format":"prettier --write src"},"_npmUser":{"name":"artale","email":"arosstale1@gmail.com"},"repository":{"url":"git+https://github.com/arosstale/openclaw-memory.git","type":"git"},"_npmVersion":"10.9.4","description":"Hindsight Memory System for OpenClaw - Retain/Recall/Reflect architecture","directories":{},"_nodeVersion":"22.22.0","dependencies":{"cors":"^2.8.0","sql.js":"^1.14.0","express":"^4.18.0","better-sqlite3":"^9.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.0.0","vitest":"^1.0.0","prettier":"^3.0.0","typescript":"^5.0.0","@types/cors":"^2.8.19","@types/node":"^20.0.0","@types/express":"^5.0.6","@types/better-sqlite3":"^7.6.0"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-memory_1.0.0_1772021435855_0.925333177927846","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@artale/openclaw-memory","version":"2.0.0","keywords":["openclaw","memory","alma","agent"],"author":{"name":"Artale","email":"arosstale1@gmail.com"},"license":"MIT","_id":"@artale/openclaw-memory@2.0.0","maintainers":[{"name":"artale","email":"arosstale1@gmail.com"}],"homepage":"https://github.com/arosstale/openclaw-memory#readme","bugs":{"url":"https://github.com/arosstale/openclaw-memory/issues"},"dist":{"shasum":"fc657a23bfa80bc2be3c1b3a7a40765f10913a65","tarball":"https://registry.npmjs.org/@artale/openclaw-memory/-/openclaw-memory-2.0.0.tgz","fileCount":23,"integrity":"sha512-dmwLGu3TYE+H3U5aPOwQu9Icg5232f3CMYT73liQoTJaLw4bkIXGeq+MetAdiplXmQXzVoqSsOouLwMhLH8maw==","signatures":[{"sig":"MEYCIQDmedAFBvWGuutcAM92/hO1LS7QYOy9VritOqHNt095BgIhAOf/T8ydEXwF1yiLIyA+rHVPLWGzepdMcnlhMEOvzHXK","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":53120},"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./alma":{"types":"./dist/alma.d.ts","import":"./dist/alma.js"},"./indexer":{"types":"./dist/indexer.d.ts","import":"./dist/indexer.js"},"./observer":{"types":"./dist/observer.d.ts","import":"./dist/observer.js"}},"gitHead":"0e283d5f8d8cc25077c8a4ebb3e4cf1574ab0700","scripts":{"test":"vitest run","build":"tsc"},"_npmUser":{"name":"artale","email":"arosstale1@gmail.com"},"repository":{"url":"git+https://github.com/arosstale/openclaw-memory.git","type":"git"},"_npmVersion":"10.9.4","description":"Memory system for OpenClaw — ALMA meta-learning + observation extraction + FTS search","directories":{},"_nodeVersion":"22.22.0","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-memory_2.0.0_1772022076027_0.13977368946758184","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@artale/openclaw-memory","version":"2.0.1","description":"Memory system for OpenClaw — ALMA meta-learning + observation extraction + FTS search","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./alma":{"types":"./dist/alma.d.ts","import":"./dist/alma.js"},"./observer":{"types":"./dist/observer.d.ts","import":"./dist/observer.js"},"./indexer":{"types":"./dist/indexer.d.ts","import":"./dist/indexer.js"}},"scripts":{"build":"tsc","test":"vitest run"},"keywords":["openclaw","memory","alma","agent"],"author":{"name":"Artale","email":"arosstale1@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/arosstale/openclaw-memory.git"},"publishConfig":{"access":"public"},"dependencies":{},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.0.0","vitest":"^1.0.0"},"_id":"@artale/openclaw-memory@2.0.1","gitHead":"449b9b97a095cfcfde65980ba2b29dc8f52c971b","bugs":{"url":"https://github.com/arosstale/openclaw-memory/issues"},"homepage":"https://github.com/arosstale/openclaw-memory#readme","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-WHmTczDm+65neAyfv8q+mSXaEIndG7M/qWXPHi1GLpNf4SAOIpOB9KD16vTfY5nuKDBg7CKXWv5IjkVhO8xj1g==","shasum":"f381144ab1bce5805b9797ac3f0c52a75a0ec04d","tarball":"https://registry.npmjs.org/@artale/openclaw-memory/-/openclaw-memory-2.0.1.tgz","fileCount":23,"unpackedSize":54390,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCVKh8Lpx1XzNzP6+A1hX/IAssf3hcGnPORPlBSlXIRcwIhAOjUvjCuszUIDh75CG/ijdt5BUjJiiCu8uGAcIJfoX/v"}]},"_npmUser":{"name":"artale","email":"arosstale1@gmail.com"},"directories":{},"maintainers":[{"name":"artale","email":"arosstale1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-memory_2.0.1_1772022229242_0.7926756880357313"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-25T12:10:35.793Z","modified":"2026-02-25T12:23:49.508Z","1.0.0":"2026-02-25T12:10:36.023Z","2.0.0":"2026-02-25T12:21:16.168Z","2.0.1":"2026-02-25T12:23:49.395Z"},"bugs":{"url":"https://github.com/arosstale/openclaw-memory/issues"},"author":{"name":"Artale","email":"arosstale1@gmail.com"},"license":"MIT","homepage":"https://github.com/arosstale/openclaw-memory#readme","keywords":["openclaw","memory","alma","agent"],"repository":{"type":"git","url":"git+https://github.com/arosstale/openclaw-memory.git"},"description":"Memory system for OpenClaw — ALMA meta-learning + observation extraction + FTS search","maintainers":[{"name":"artale","email":"arosstale1@gmail.com"}],"readme":"# Hindsight Memory System for OpenClaw\r\n\r\n> Production-grade agent memory that learns and improves over time.\r\n\r\nOpenClaw agents can now **retain, recall, and reflect** — automatically extracting structured knowledge from daily logs, searching semantically and semantically, updating confidence in learned opinions, and optimizing their own memory design.\r\n\r\nThis system implements the **Hindsight Memory Architecture** (retain/recall/reflect) combined with **ALMA** (Algorithm Learning via Meta-learning Agents) to make agent memory both **human-readable** (Markdown-backed) and **machine-optimizable**.\r\n\r\n---\r\n\r\n## What Problem Does This Solve?\r\n\r\n**OpenClaw's native memory is append-only Markdown.** Great for journaling, terrible for recall:\r\n\r\n- ❌ \"What did I decide about X?\" — requires re-reading 100 files\r\n- ❌ \"What changed about Alice?\" — no version history of beliefs\r\n- ❌ \"Why did that strategy fail before?\" — no searchable failure log\r\n- ❌ \"Which memories actually matter?\" — no optimization\r\n\r\n**This system solves it:**\r\n\r\n- ✅ Automatic fact extraction from daily logs (Observational Memory)\r\n- ✅ Entity-centric summaries (`bank/entities/Alice.md`)\r\n- ✅ Confidence-bearing opinions that evolve with evidence\r\n- ✅ Temporal queries (\"what was true in November?\")\r\n- ✅ ALMA learns which memory designs maximize agent performance\r\n- ✅ Everything stays offline, auditable, and git-backed\r\n\r\n---\r\n\r\n## Architecture\r\n\r\n### Canonical Store (Git-Friendly)\r\n\r\nYour workspace is the source of truth — human-readable Markdown:\r\n\r\n```\r\n~/.openclaw/workspace/\r\n├── MEMORY.md                  # core: durable facts + preferences\r\n├── memory/\r\n│   ├── 2026-02-24.md         # daily log (append-only)\r\n│   ├── 2026-02-23.md\r\n│   └── ...\r\n└── bank/                      # curated, typed memory\r\n    ├── world.md              # objective facts\r\n    ├── experience.md         # what happened (first-person)\r\n    ├── opinions.md           # prefs/judgments + confidence + evidence\r\n    └── entities/\r\n        ├── Alice.md\r\n        ├── The-Castle.md\r\n        └── ...\r\n```\r\n\r\n### Derived Store (Machine Recall)\r\n\r\nAn offline-first SQLite index powers fast, semantic search:\r\n\r\n```\r\n~/.openclaw/workspace/.memory/index.sqlite\r\n```\r\n\r\n- **FTS5** for lexical search (fast, tiny, no ML)\r\n- **Embeddings** for semantic search (optional, local or remote)\r\n- **Always rebuildable** from Markdown (never the source of truth)\r\n\r\n### Operational Loop (Retain → Recall → Reflect)\r\n\r\n```\r\nDaily Log (YYYY-MM-DD.md)\r\n        ↓\r\n    [Retain] Extract structured facts\r\n        ↓\r\n  SQLite Index (FTS + embeddings)\r\n        ↓\r\n    [Recall] Agent queries via tools\r\n        ↓\r\n  bank/entities/*.md, bank/opinions.md\r\n        ↓\r\n   [Reflect] Daily job updates summaries & beliefs\r\n        ↓\r\n    MEMORY.md grows with stable facts\r\n```\r\n\r\n---\r\n\r\n## Components\r\n\r\n| Component | What It Does | Language |\r\n|-----------|------------|----------|\r\n| **ALMA** (meta-learning) | Evolves memory design to maximize agent performance | Python (1,270 LOC) |\r\n| **Observational Memory** | Extracts temporal, entity-linked facts from logs | Python (1,529 LOC) |\r\n| **Knowledge Indexer** | Builds FTS + embedding index over Markdown | Python (248 LOC) |\r\n| **Scripts** | Automation: bootstrap, sync, compress, stress-test | Shell (905 LOC) |\r\n| **Integration** | ALMA optimizer, reranker, PAOM exporter | Python (1,072 LOC) |\r\n\r\n**Total: 11,695 lines of real, working Python code.**\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n### 1. Install\r\n\r\n```bash\r\nnpm install @artale/openclaw-memory\r\n```\r\n\r\n### 2. Use It\r\n\r\n```typescript\r\nimport { ALMAAgent } from '@artale/openclaw-memory/alma';\r\nimport { ObserverAgent } from '@artale/openclaw-memory/memory';\r\nimport { MemoryIndexer } from '@artale/openclaw-memory/search';\r\n\r\n// ALMA: meta-learning memory optimizer\r\nconst alma = new ALMAAgent({ dbPath: './memory.db' });\r\n\r\n// Observer: extract facts from conversations\r\nconst observer = new ObserverAgent({ provider: 'anthropic' });\r\n\r\n// Indexer: full-text search over memory files\r\nconst indexer = new MemoryIndexer({\r\n  workspace: '~/.openclaw/workspace',\r\n  dbPath: './index.db',\r\n});\r\n```\r\n\r\n### 3. Configure OpenClaw to Use It\r\n\r\nIn your OpenClaw config (`~/.openclaw/openclaw.json`):\r\n\r\n```json\r\n{\r\n  \"agents\": {\r\n    \"defaults\": {\r\n      \"workspace\": \"~/.openclaw/workspace\",\r\n      \"memorySearch\": {\r\n        \"enabled\": true,\r\n        \"provider\": \"openai\",\r\n        \"model\": \"text-embedding-3-small\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### 4. Start Using It\r\n\r\n**Write to daily log:**\r\n```bash\r\n# Append to today's log\r\necho \"## Retain\r\n- W @Alice: Still prefers async communication\r\n- B: Fixed the connection pool leak in server.ts\r\n- O(c=0.92) @Alice: Values speed over perfection\" >> ~/.openclaw/workspace/memory/$(date +%Y-%m-%d).md\r\n```\r\n\r\n**Agent recalls:**\r\n```\r\nUser: \"What does Alice prefer?\"\r\nAgent: [calls memory_search] → returns facts tagged @Alice with sources + confidence\r\n```\r\n\r\n**Reflection job (daily):**\r\n```bash\r\n# Updates bank/entities/Alice.md + bank/opinions.md\r\npython .openclaw/alma/alma_agent.py --reflect\r\n```\r\n\r\n---\r\n\r\n## Key Features\r\n\r\n### Hindsight Memory (Retain/Recall/Reflect)\r\n\r\n**Retain:** Structured fact extraction\r\n- Type tags: `W` (world), `B` (biographical), `O` (opinion), `S` (summary)\r\n- Entity mentions: `@Alice`, `@The-Castle`\r\n- Opinion confidence: `O(c=0.0..1.0)`\r\n\r\n**Recall:** Smart search\r\n- Lexical (FTS5): exact names, IDs, commands\r\n- Semantic (embeddings): \"what does Alice prefer?\" vs \"Alice's preferences\"\r\n- Temporal: \"what happened in November?\" \r\n- Entity-centric: \"tell me about Alice\"\r\n\r\n**Reflect:** Auto-update summaries\r\n- `bank/entities/*.md` updated from recent facts\r\n- Opinion confidence evolves with reinforcement/contradiction\r\n- `MEMORY.md` grows with stable, durable facts\r\n\r\n### ALMA (Self-Improving Memory Design)\r\n\r\nThe agent can improve its own memory system by:\r\n1. Proposing mutations to the memory structure\r\n2. Evaluating which designs maximize performance\r\n3. Archiving best designs for future use\r\n\r\n(Research-grade; useful for long-running agents)\r\n\r\n### Observational Memory (Temporal Anchoring)\r\n\r\nCaptures **when things were decided**, not just what was decided:\r\n\r\n```\r\n2026-02-24 14:30 [High] User stated Alice prefers async > sync. (meaning Feb 24, 2026)\r\n2026-02-24 14:45 [Medium] Implemented connection pool retry logic.\r\n```\r\n\r\n---\r\n\r\n## Integration with OpenClaw\r\n\r\n### Memory Tools (Provided by OpenClaw)\r\n\r\nYour agent gets two tools automatically:\r\n\r\n```python\r\n# Semantic search over memory\r\nmemory_search(query, k=5, since=\"30d\")\r\n# Returns: [{ kind, timestamp, entities, content, source }, ...]\r\n\r\n# Direct file read\r\nmemory_get(path, start_line=None, num_lines=None)\r\n# Returns: { text, path }\r\n```\r\n\r\n### Agent Workflow\r\n\r\n1. **Daily standup:** Agent reads yesterday's log + today's MEMORY.md\r\n2. **Session:** Agent calls `memory_search` to recall relevant facts\r\n3. **End of session:** Pre-compaction flush writes durable facts to `memory/YYYY-MM-DD.md`\r\n4. **Overnight:** Reflection job runs → updates `bank/` → feeds into next day's MEMORY.md\r\n\r\n---\r\n\r\n## Configuration\r\n\r\n### Minimal (Just Works)\r\n\r\n```json\r\n{\r\n  \"agents\": {\r\n    \"defaults\": {\r\n      \"workspace\": \"~/.openclaw/workspace\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### With Semantic Search\r\n\r\n```json\r\n{\r\n  \"agents\": {\r\n    \"defaults\": {\r\n      \"memorySearch\": {\r\n        \"enabled\": true,\r\n        \"provider\": \"openai\",\r\n        \"model\": \"text-embedding-3-small\",\r\n        \"remote\": {\r\n          \"apiKey\": \"sk-...\"\r\n        }\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### With Local Embeddings (Offline)\r\n\r\n```json\r\n{\r\n  \"agents\": {\r\n    \"defaults\": {\r\n      \"memorySearch\": {\r\n        \"provider\": \"local\",\r\n        \"local\": {\r\n          \"modelPath\": \"hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf\"\r\n        }\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n## Philosophy\r\n\r\n**Three principles:**\r\n\r\n1. **Markdown is source of truth.** Humans read it, git tracks it, agents extend it.\r\n2. **Offline-first.** Works on laptop, castle, RPi. No cloud required.\r\n3. **Explainable recall.** Every fact is citable (file + line). Confidence is tracked.\r\n\r\n---\r\n\r\n## Files\r\n\r\n- **`.openclaw/alma/`** — ALMA agent (meta-learning)\r\n- **`.openclaw/observational_memory/`** — Fact extraction + temporal anchoring\r\n- **`.openclaw/knowledge/`** — Indexer + searcher\r\n- **`.openclaw/integrations/`** — ALMA optimizer, reranker, exporters\r\n- **`.openclaw/scripts/`** — Automation (init, sync, compress, stress-test)\r\n- **`scripts/`** — MSAM export, health checks\r\n\r\n---\r\n\r\n## Status\r\n\r\n- ✅ ALMA agent (working)\r\n- ✅ Observational Memory (working)\r\n- ✅ Knowledge indexing (working)\r\n- ✅ OpenClaw integration (ready)\r\n- ⏳ CI/CD (in progress)\r\n- ⏳ Full docs (in progress)\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nThis is a research-grade production system. Fork, customize, and PR improvements back.\r\n\r\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT — Use, modify, share freely. Attribution appreciated.\r\n\r\n---\r\n\r\n## Credits\r\n\r\n- **Hindsight Technical Report** — Retain/Recall/Reflect architecture inspiration\r\n- **ALMA Paper (arXiv 2602.07755)** — Meta-learning agents\r\n- **OpenClaw** — The framework we're optimizing for\r\n- **Artale** — Implementation & integration\r\n\r\n---\r\n\r\n**🧠 Your agent now has a production-grade memory system. Time to build.**\r\n","readmeFilename":"README.md"}