{"_id":"@akalsey/openclaw-memory","_rev":"3-995b2bae7e385e7ab26433ca726ed8c2","name":"@akalsey/openclaw-memory","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@akalsey/openclaw-memory","version":"0.1.0","_id":"@akalsey/openclaw-memory@0.1.0","maintainers":[{"name":"akalsey","email":"adam@kalsey.com"}],"dist":{"shasum":"10e78ea3509b5a0f6fd80348d313da74c304122c","tarball":"https://registry.npmjs.org/@akalsey/openclaw-memory/-/openclaw-memory-0.1.0.tgz","fileCount":14,"integrity":"sha512-m1KCXmOmkNNsNh6squK+AU4Q0MrYf/ihr0C7WAigl+OQow33aYvspJTpeonxB3hUbWEo1H0C0rRlrNShpaCwmg==","signatures":[{"sig":"MEUCICoFSGc2KMEW2lv/W6eawQ9BHwA2KvhesBWHXWXDgPGGAiEApOZ4sIaVjui3yn1KBpL6ukyEK30g5Gvw8AAM5HSKxP4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29433},"main":"./dist/index.js","type":"module","exports":{".":"./dist/index.js"},"gitHead":"f1b1febcca21adfba5d6ba11efc67803d1b445ca","scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"akalsey","email":"adam@kalsey.com"},"openclaw":{"compat":{"pluginApi":">=2026.3.24-beta.2","minGatewayVersion":"2026.3.24-beta.2"},"install":{"localPath":"."},"extensions":["./dist/index.js"]},"_npmVersion":"11.13.0","description":"A per-turn-lean memory plugin. Small always-loaded core, explicit on-demand retrieval. Memory is markdown files on disk, search is BM25, and the corpus stays manageable through deliberate writes rather than passive capture.","directories":{},"_nodeVersion":"26.0.0","dependencies":{"chokidar":"^3.6.0","gray-matter":"^4.0.3"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","openclaw":"latest","typescript":"^5.5.0","@types/node":"^22.0.0"},"peerDependencies":{"openclaw":">=2026.3.24-beta.2"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-memory_0.1.0_1779425080104_0.6539509238026542","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@akalsey/openclaw-memory","version":"0.1.1","_id":"@akalsey/openclaw-memory@0.1.1","maintainers":[{"name":"akalsey","email":"adam@kalsey.com"}],"dist":{"shasum":"db5f4a292aef6e62a5512cb1f4f091af9f05c658","tarball":"https://registry.npmjs.org/@akalsey/openclaw-memory/-/openclaw-memory-0.1.1.tgz","fileCount":14,"integrity":"sha512-CMwtniKck8tYb4bThLMfIpHNxQaPwZK1+Gp+nm2QrF6Uu1ALQXgL40vC7LUmKY8u+8soF0XinAAJAqJ9sCblVg==","signatures":[{"sig":"MEQCIAKAY4OH0de3ft+Tudb2z9m7zbbHbWsJiljVAWHaM5mXAiBlrEUDIGVspJNmR+g3wV9UnJs3sqLEwU6SwNY+2h+tSg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29476},"main":"./dist/index.js","type":"module","exports":{".":"./dist/index.js"},"gitHead":"b70d59d46562e15bcf869902d2a8227a82ab834d","scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"akalsey","email":"adam@kalsey.com"},"openclaw":{"compat":{"pluginApi":">=2026.3.24-beta.2","minGatewayVersion":"2026.3.24-beta.2"},"install":{"localPath":"."},"extensions":["./dist/index.js"]},"_npmVersion":"11.13.0","description":"A per-turn-lean memory plugin. Small always-loaded core, explicit on-demand retrieval. Memory is markdown files on disk, search is BM25, and the corpus stays manageable through deliberate writes rather than passive capture.","directories":{},"_nodeVersion":"26.0.0","dependencies":{"chokidar":"^3.6.0","gray-matter":"^4.0.3"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","openclaw":"latest","typescript":"^5.5.0","@types/node":"^22.0.0"},"peerDependencies":{"openclaw":">=2026.3.24-beta.2"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-memory_0.1.1_1779425653708_0.9086432765743586","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@akalsey/openclaw-memory","version":"0.1.2","type":"module","main":"./dist/index.js","exports":{".":"./dist/index.js"},"scripts":{"build":"tsc","prepublishOnly":"npm run build","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit"},"openclaw":{"extensions":["./dist/index.js"],"compat":{"pluginApi":">=2026.3.24-beta.2","minGatewayVersion":"2026.3.24-beta.2"},"install":{"localPath":"."}},"dependencies":{"chokidar":"^3.6.0","gray-matter":"^4.0.3"},"devDependencies":{"@types/node":"^22.0.0","openclaw":"latest","typescript":"^5.5.0","vitest":"^2.0.0"},"peerDependencies":{"openclaw":">=2026.3.24-beta.2"},"gitHead":"034d5cec9e832933ec3a2cfa6273b6fdcc00d3d4","_id":"@akalsey/openclaw-memory@0.1.2","description":"A per-turn-lean memory plugin. Small always-loaded core, explicit on-demand retrieval. Memory is markdown files on disk, search is BM25, and the corpus stays manageable through deliberate writes rather than passive capture.","_nodeVersion":"26.0.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-JEpHMYcMFyzqti8RCu9n9gQDApwBK2SC/2voFnxXvnQ9SHB0aUI3pHXZvea6PwRQe3rJ31hpzx32XssNMLIBpA==","shasum":"14f802b4695be03df4daa49af24ab9cad21834dd","tarball":"https://registry.npmjs.org/@akalsey/openclaw-memory/-/openclaw-memory-0.1.2.tgz","fileCount":14,"unpackedSize":29827,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICq8kysM+ioF6ShzM82OB+HMH5uV3ipoHg5OaYKdzl2OAiEAhZimvDTr1Yn6ZLpgDYqNL3LoigNDXuRpDS8+p/ziqrE="}]},"_npmUser":{"name":"akalsey","email":"adam@kalsey.com"},"directories":{},"maintainers":[{"name":"akalsey","email":"adam@kalsey.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-memory_0.1.2_1779426118702_0.37388103706329723"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-22T04:44:39.898Z","modified":"2026-05-22T05:01:59.020Z","0.1.0":"2026-05-22T04:44:40.241Z","0.1.1":"2026-05-22T04:54:13.845Z","0.1.2":"2026-05-22T05:01:58.907Z"},"description":"A per-turn-lean memory plugin. Small always-loaded core, explicit on-demand retrieval. Memory is markdown files on disk, search is BM25, and the corpus stays manageable through deliberate writes rather than passive capture.","maintainers":[{"name":"akalsey","email":"adam@kalsey.com"}],"readme":"# openclaw-memory\n\nA per-turn-lean memory plugin. Small always-loaded core, explicit on-demand retrieval. Memory is markdown files on disk, search is BM25, and the corpus stays manageable through deliberate writes rather than passive capture.\n\n---\n\n## Setup\n\n### Install\n\n```bash\nopenclaw plugins install npm:@akalsey/openclaw-memory\n```\n\n### Configuration\n\n```json\n{\n  \"plugins\": {\n    \"sapience-memory\": {\n      \"memoryPath\": \"~/.openclaw/memory\",\n      \"search\": {\n        \"defaultLimit\": 5,\n        \"maxLimit\": 20,\n        \"recencyBoostDays\": 30,\n        \"recencyBoostMax\": 1.2\n      },\n      \"write\": {\n        \"requireTags\": true,\n        \"minTags\": 1,\n        \"maxTags\": 12\n      }\n    }\n  }\n}\n```\n\nAll settings are optional — defaults above are used if omitted.\n\n### Storage layout\n\n```\n~/.openclaw/memory/\n├── indexed/\n│   ├── 2026-05-20-posthog-billing-a3f9b2c1.md\n│   └── ...\n└── _searches.json\n```\n\nMemories are plain markdown files. You can read, edit, and grep them in any editor. External edits are picked up automatically via filesystem watching.\n\n---\n\n## Memory entry format\n\n```markdown\n---\nid: mem_2026-05-20_a3f9b2c1\ncreated: 2026-05-20T14:30:00Z\nupdated: 2026-05-20T14:30:00Z\ntags: [posthog, billing, group-identify]\nsource: session\nscore: 0.7\nsize_tier: full\nlast_accessed: 2026-05-20T14:30:00Z\naccess_count: 3\n---\n\n# PostHog group identify billing investigation\n\nPostHog charges separately for groupIdentify events under the data warehouse\nSKU. Our May 2026 spike traced to a deploy that called groupIdentify on every\npage view. Fix: call it once per session, cache client-side.\n```\n\n---\n\n## Tools\n\n| Tool | What it does |\n|------|-------------|\n| `memory_search(query, tags?, limit?)` | BM25 search, returns excerpts + metadata |\n| `memory_get(id)` | Full content of one entry; updates access metadata |\n| `memory_write(content, tags)` | Creates new entry, returns id |\n| `memory_supersede(old_id, new_content, new_tags, reason)` | Replaces outdated entry |\n| `memory_stats()` | Corpus stats: count, size, top tags, recent activity |\n| `memory_recent_searches(limit?)` | Last N searches with result counts |\n\n---\n\n## Using it effectively\n\nThe agent learns when to search from the SKILL.md that ships with the plugin. Key behaviors to reinforce:\n\n- When core memory has a pointer to indexed memory → agent searches before answering\n- After an investigation produces findings → agent writes a memory entry\n- When a memory contradicts current knowledge → agent supersedes rather than leaving conflicts\n\n**Tags are the most important thing you control.** The agent writes them at creation time. Good tags are terms you'd type in a future search: domain names, topic words, project names. Sparse tags make recall worse; there's no downside to 8 tags if they're all relevant.\n\n---\n\n## Inspecting memory\n\n```bash\n# How many entries, top tags\nopenclaw memory stats\n\n# Recent searches and their result counts\nopenclaw memory recent-searches\n\n# Browse entries directly\nls ~/.openclaw/memory/indexed/\ngrep -l \"billing\" ~/.openclaw/memory/indexed/\ncat ~/.openclaw/memory/indexed/2026-05-20-posthog-billing-a3f9b2c1.md\n```\n\n---\n\n## Troubleshooting\n\n**Agent answers from training data instead of memory**\nThe agent didn't search. Check the SKILL.md is loading (visible in session start). Add explicit pointers in core memory: \"Indexed memory has notes on [topic].\" This gives the agent a concrete cue to search.\n\n**Search returns nothing for a topic you know exists**\nTry different query terms — BM25 is lexical, not semantic. If the entry uses different vocabulary than your query, it won't match. Check what terms are in the actual entry with `grep`. Add more tags when you write entries.\n\n**Index out of sync after external edits**\nThe chokidar watcher picks up external file changes in real time. If it seems stale, restart the OpenClaw session to force a full reload.\n\n**Corpus growing too large**\nv1 has no automatic decay. Prune manually by deleting files from `~/.openclaw/memory/indexed/` or using `memory_supersede` to replace bulky entries with summaries. Semantic search + decay-as-pruning is planned for v2.\n\n**Duplicate or contradictory entries**\nUse `memory_supersede`. It deletes the old entry and creates a new one, appending the reason for traceability. Nothing in v1 detects contradictions automatically — the agent notices during retrieval and resolves them on encountering them.\n","readmeFilename":"README.md"}