clawvault

Category: Tools & Productivity | Uploader: Versatly | Downloads: 0 | Version: v1.0（Latest）

Agent memory system with memory graph, context profiles, checkpoint/recover, structured storage, semantic search, and observational memory. Use when: storing/searching memories, preventing context death, graph-aware context retrieval, repairing broken sessions. Don't use when: general file I/O.

Changelog: Source: GitHub https://github.com/Versatly/clawvault

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 471 B
  - 📄 cursor-agent-notify.yml 1.2 KB
- 📄 RELEASE_TEMPLATE.md 1.5 KB
📁 autoresearch/
- 📄 experiment.sh 2.1 KB
- 📄 program.md 7.6 KB
- 📄 results.tsv 403 B
- 📄 run-baseline-gemini.json 11.6 KB
- 📄 run-baseline-mock.json 12.8 KB
- 📄 run-latest.json 8.0 KB
- 📄 run-mock-baseline.json 12.7 KB
- 📄 run-mock.json 10.2 KB
- 📄 run-repeat-1.json 8.2 KB
- 📄 run-repeat-2.json 7.6 KB
- 📄 run-repeat-3.json 7.6 KB
- 📄 run-repeat-4.json 7.6 KB
- 📄 run-repeat-5.json 7.6 KB
- 📄 run-repeat-6.json 7.6 KB
- 📄 run.sh 1.7 KB
📁 benchmarks/
- 📄 claw-pod.yml 1.0 KB
- 📄 Clawfile 604 B
📁 bin/
- 📁 test-helpers/
  - 📄 cli-command-fixtures.js 3.7 KB
- 📄 clawvault.js 2.8 KB
- 📄 command-registration.test.js 6.2 KB
- 📄 command-runtime.js 2.8 KB
- 📄 command-runtime.test.js 4.7 KB
- 📄 help-contract.test.js 2.6 KB
- 📄 register-config-commands.js 4.9 KB
- 📄 register-config-route-commands.test.js 4.1 KB
- 📄 register-core-commands.js 12.6 KB
- 📄 register-core-commands.test.js 2.9 KB
- 📄 register-kanban-commands.js 2.0 KB
- 📄 register-kanban-commands.test.js 2.5 KB
- 📄 register-maintenance-commands.js 13.0 KB
- 📄 register-project-commands.js 7.1 KB
- 📄 register-project-commands.test.js 5.8 KB
- 📄 register-query-commands.js 15.7 KB
- 📄 register-query-commands.test.js 3.1 KB
- 📄 register-resilience-commands.js 6.1 KB
- 📄 register-resilience-commands.test.js 2.7 KB
- 📄 register-route-commands.js 3.8 KB
- 📄 register-session-lifecycle-commands.js 8.2 KB
- 📄 register-tailscale-commands.js 3.8 KB
- 📄 register-task-commands.js 12.0 KB
- 📄 register-task-commands.test.js 2.3 KB
- 📄 register-template-commands.js 2.5 KB
- 📄 register-template-commands.test.js 2.8 KB
- 📄 register-vault-operations-commands.js 9.6 KB
📁 dashboard/
- 📁 lib/
  - 📄 graph-diff.js 2.9 KB
  - 📄 graph-diff.test.js 3.0 KB
  - 📄 vault-parser.js 15.6 KB
  - 📄 vault-parser.test.js 8.2 KB
- 📁 public/
  - 📄 app.js 23.6 KB
  - 📄 index.html 1.8 KB
  - 📄 styles.css 3.5 KB
- 📄 server.js 9.1 KB
📁 docs/
- 📁 getting-started/
  - 📄 installation.md 1.9 KB
- 📄 clawhub-security-release-playbook.md 2.8 KB
- 📄 openclaw-plugin-usage.md 9.0 KB
📁 eval/
- 📄 run_v35_full.py 78.7 KB
📁 examples/
- 📁 observer-bench/
  - 📄 claw-pod.yml 2.6 KB
  - 📄 Clawfile 436 B
  - 📄 README.md 1.5 KB
📁 hooks/
- 📁 clawvault/
  - 📄 handler.js 50.7 KB
  - 📄 handler.test.js 17.5 KB
  - 📄 HOOK.md 5.2 KB
  - 📄 integrity.js 3.0 KB
  - 📄 integrity.test.js 1.1 KB
  - 📄 openclaw.plugin.json 6.7 KB
📁 packages/
- 📁 plugin/
  - 📁 scripts/
    
    📄 build-embeddings.mjs 2.6 KB
    
    📄 semantic-rerank.mjs 3.5 KB
📁 python/
- 📁 src/
  - 📁 clawvault/
    
    📄 __init__.py 431 B
    
    📄 constants.py 925 B
    
    📄 frontmatter.py 1.5 KB
    
    📄 models.py 1.2 KB
    
    📄 py.typed 1 B
    
    📄 search.py 4.2 KB
    
    📄 semantic.py 4.6 KB
    
    📄 vault.py 12.6 KB
- 📁 tests/
  - 📄 test_vault.py 4.0 KB
- 📄 .gitignore 59 B
- 📄 pyproject.toml 1.4 KB
- 📄 README.md 2.8 KB
📁 schemas/
- 📄 compat-artifact-bundle-manifest-validator-output.schema.json 12.8 KB
- 📄 compat-artifact-bundle-validator-output.schema.json 12.8 KB
- 📄 compat-artifact-bundle.manifest.json 2.1 KB
- 📄 compat-artifact-bundle.manifest.schema.json 9.3 KB
- 📄 compat-case-report.schema.json 1.0 KB
- 📄 compat-report-schema-validator-output.schema.json 1.8 KB
- 📄 compat-summary-validator-output.schema.json 1.9 KB
- 📄 compat-summary.schema.json 4.0 KB
- 📄 compat-validator-result-verifier-output.schema.json 1.4 KB
- 📄 json-schema-validator-output.schema.json 1.6 KB
📁 scripts/
- 📄 observe-active-sessions.sh 642 B
- 📄 observe-stale-sessions.sh 1.4 KB
📁 src/
- 📁 capture/
  - 📄 extractor.test.ts 1.6 KB
  - 📄 extractor.ts 6.0 KB
  - 📄 index.ts 425 B
  - 📄 quality.test.ts 1.9 KB
  - 📄 quality.ts 5.0 KB
  - 📄 service.test.ts 2.2 KB
  - 📄 service.ts 6.7 KB
  - 📄 types.ts 1.0 KB
- 📁 cli/
  - 📄 index.ts 1.1 KB
- 📁 commands/
  - 📄 archive.test.ts 3.2 KB
  - 📄 archive.ts 1.7 KB
  - 📄 backlog.test.ts 2.9 KB
  - 📄 backlog.ts 4.8 KB
  - 📄 benchmark.test.ts 3.3 KB
  - 📄 benchmark.ts 2.8 KB
  - 📄 blocked.test.ts 2.3 KB
  - 📄 blocked.ts 1.9 KB
  - 📄 canvas.test.ts 3.8 KB
  - 📄 canvas.ts 974 B
  - 📄 checkpoint.test.ts 5.5 KB
  - 📄 checkpoint.ts 6.4 KB
  - 📄 compat.test.ts 11.2 KB
  - 📄 compat.ts 12.1 KB
  - 📄 context.test.ts 14.8 KB
  - 📄 context.ts 27.1 KB
  - 📄 doctor.test.ts 7.2 KB
  - 📄 doctor.ts 25.9 KB
  - 📄 embed.test.ts 3.0 KB
  - 📄 embed.ts 2.2 KB
  - 📄 entities.test.ts 5.8 KB
  - 📄 entities.ts 2.8 KB
  - 📄 graph.test.ts 1.4 KB
  - 📄 graph.ts 2.2 KB
  - 📄 inbox.test.ts 2.2 KB
  - 📄 inbox.ts 2.1 KB
  - 📄 inject.test.ts 6.4 KB
  - 📄 inject.ts 6.1 KB
  - 📄 kanban.test.ts 5.1 KB
  - 📄 kanban.ts 15.1 KB
  - 📄 link.test.ts 4.7 KB
  - 📄 link.ts 7.9 KB
  - 📄 maintain.test.ts 5.3 KB
  - 📄 maintain.ts 4.3 KB
  - 📄 migrate-observations.test.ts 2.3 KB
  - 📄 migrate-observations.ts 3.5 KB
  - 📄 migrate.test.ts 12.2 KB
  - 📄 migrate.ts 9.0 KB
  - 📄 observe.test.ts 6.3 KB
  - 📄 observe.ts 10.4 KB
  - 📄 patch.test.ts 5.3 KB
  - 📄 patch.ts 4.3 KB
  - 📄 project.test.ts 3.5 KB
  - 📄 project.ts 15.0 KB
  - 📄 rebuild-embeddings.test.ts 6.8 KB
  - 📄 rebuild-embeddings.ts 4.3 KB
  - 📄 rebuild.test.ts 1.7 KB
  - 📄 rebuild.ts 3.8 KB
  - 📄 recall.test.ts 2.4 KB
  - 📄 recall.ts 1.1 KB
  - 📄 recover.test.ts 5.3 KB
  - 📄 recover.ts 9.9 KB
  - 📄 reflect.test.ts 3.7 KB
  - 📄 reflect.ts 1.8 KB
  - 📄 repair-session.test.ts 10.9 KB
  - 📄 repair-session.ts 5.1 KB
  - 📄 replay.test.ts 1.6 KB
  - 📄 replay.ts 7.8 KB
  - 📄 session-recap.test.ts 6.2 KB
  - 📄 session-recap.ts 10.5 KB
  - 📄 setup.test.ts 1.9 KB
  - 📄 setup.ts 13.5 KB
  - 📄 shell-init.test.ts 1.2 KB
  - 📄 shell-init.ts 1.3 KB
  - 📄 sleep.test.ts 5.6 KB
  - 📄 sleep.ts 7.7 KB
  - 📄 status.test.ts 7.8 KB
  - 📄 status.ts 11.5 KB
  - 📄 sync-bd.test.ts 679 B
  - 📄 sync-bd.ts 4.1 KB
  - 📄 tailscale.test.ts 10.6 KB
  - 📄 tailscale.ts 16.8 KB
  - 📄 task.test.ts 7.6 KB
  - 📄 task.ts 10.1 KB
  - 📄 template.test.ts 3.6 KB
  - 📄 template.ts 5.5 KB
  - 📄 wake.test.ts 5.6 KB
  - 📄 wake.ts 10.0 KB
- 📁 entities/
  - 📄 index.ts 210 B
  - 📄 synthesis.test.ts 2.5 KB
  - 📄 synthesis.ts 10.2 KB
  - 📄 types.ts 355 B
- 📁 lib/
  - 📁 maintenance/
    
    📄 curator-worker.ts 2.8 KB
    
    📄 distiller-worker.ts 3.8 KB
    
    📄 heuristics.ts 4.6 KB
    
    📄 janitor-worker.ts 6.6 KB
    
    📄 llm.ts 2.8 KB
    
    📄 log.ts 1.3 KB
    
    📄 state.ts 1.8 KB
    
    📄 surveyor-worker.ts 4.5 KB
    
    📄 types.ts 803 B
    
    📄 worker-utils.ts 6.7 KB
    
    📄 workers.ts 230 B
  - 📄 auto-linker.test.ts 4.9 KB
  - 📄 auto-linker.ts 6.3 KB
  - 📄 backlinks.test.ts 3.5 KB
  - 📄 backlinks.ts 6.3 KB
  - 📄 canvas-default-template.test.ts 4.0 KB
  - 📄 canvas-default-template.ts 5.1 KB
  - 📄 canvas-layout.test.ts 6.3 KB
  - 📄 canvas-layout.ts 6.2 KB
  - 📄 canvas-templates.test.ts 3.3 KB
  - 📄 canvas-templates.ts 226 B
  - 📄 config-manager.test.ts 9.3 KB
  - 📄 config-manager.ts 31.4 KB
  - 📄 config.test.ts 6.8 KB
  - 📄 config.ts 4.3 KB
  - 📄 context-profile.test.ts 1.3 KB
  - 📄 context-profile.ts 1.4 KB
  - 📄 embedding-store.ts 5.0 KB
  - 📄 entity-index.test.ts 3.1 KB
  - 📄 entity-index.ts 2.6 KB
  - 📄 fact-extractor.test.ts 3.8 KB
  - 📄 fact-extractor.ts 11.6 KB
  - 📄 fact-store.test.ts 5.9 KB
  - 📄 fact-store.ts 7.8 KB
  - 📄 hosted-embeddings.ts 6.1 KB
  - 📄 hosted-rerank.ts 3.4 KB
  - 📄 hybrid-search.test.ts 1.3 KB
  - 📄 hybrid-search.ts 6.4 KB
  - 📄 in-process-search.test.ts 4.0 KB
  - 📄 in-process-search.ts 15.2 KB
  - 📄 inbox.ts 4.9 KB
  - 📄 inject-utils.test.ts 5.2 KB
  - 📄 inject-utils.ts 20.6 KB
  - 📄 ledger.test.ts 5.8 KB
  - 📄 ledger.ts 10.6 KB
  - 📄 llm-adapter.test.ts 9.4 KB
  - 📄 llm-adapter.ts 6.9 KB
  - 📄 llm-provider.test.ts 13.4 KB
  - 📄 llm-provider.ts 12.9 KB
  - 📄 memory-graph.test.ts 8.1 KB
  - 📄 memory-graph.ts 17.6 KB
  - 📄 observation-format.test.ts 2.1 KB
  - 📄 observation-format.ts 6.9 KB
  - 📄 observation-reader.test.ts 3.4 KB
  - 📄 observation-reader.ts 2.2 KB
  - 📄 primitive-templates.test.ts 6.9 KB
  - 📄 primitive-templates.ts 13.9 KB
  - 📄 project-template-fallback.test.ts 1.6 KB
  - 📄 project-utils.test.ts 8.6 KB
  - 📄 project-utils.ts 16.9 KB
  - 📄 qmd-collections.test.ts 4.4 KB
  - 📄 qmd-collections.ts 5.2 KB
  - 📄 qmd-embedding-recovery.test.ts 5.0 KB
  - 📄 qmd-embedding-recovery.ts 6.4 KB
  - 📄 search.test.ts 9.1 KB
  - 📄 search.ts 18.8 KB
  - 📄 session-repair.test.ts 5.6 KB
  - 📄 session-repair.ts 9.9 KB
  - 📄 session-utils.test.ts 6.1 KB
  - 📄 session-utils.ts 5.8 KB
  - 📄 tailscale.test.ts 15.8 KB
  - 📄 tailscale.ts 28.4 KB
  - 📄 task-template-fallback.test.ts 1.5 KB
  - 📄 task-utils.test.ts 20.9 KB
  - 📄 task-utils.ts 26.5 KB
  - 📄 template-engine.test.ts 1.1 KB
  - 📄 template-engine.ts 805 B
  - 📄 time.test.ts 795 B
  - 📄 time.ts 462 B
  - 📄 token-counter.test.ts 1.2 KB
  - 📄 token-counter.ts 1.0 KB
  - 📄 transition-ledger.test.ts 8.4 KB
  - 📄 transition-ledger.ts 6.4 KB
  - 📄 vault-qmd-config.test.ts 4.1 KB
  - 📄 vault-qmd-config.ts 2.8 KB
  - 📄 vault-stats.test.ts 11.5 KB
  - 📄 vault-stats.ts 11.7 KB
  - 📄 vault-template-init.test.ts 3.2 KB
  - 📄 vault.test.ts 11.9 KB
  - 📄 vault.ts 38.6 KB
  - 📄 webdav.test.ts 21.1 KB
  - 📄 webdav.ts 23.2 KB
  - 📄 wiki-links.ts 3.8 KB
- 📁 observer/
  - 📁 benchmark/
    
    📄 fixtures.ts 2.4 KB
    
    📄 format.ts 1.9 KB
    
    📄 index.ts 680 B
    
    📄 runner.test.ts 3.3 KB
    
    📄 runner.ts 5.1 KB
    
    📄 scoring.test.ts 3.6 KB
    
    📄 scoring.ts 10.2 KB
    
    📄 types.ts 2.4 KB
  - 📄 active-session-observer.test.ts 14.4 KB
  - 📄 active-session-observer.ts 20.0 KB
  - 📄 archive.test.ts 5.0 KB
  - 📄 archive.ts 1.8 KB
  - 📄 compressor.openclaw-sourceprefix.test.ts 1.6 KB
  - 📄 compressor.openclaw-toolresult.test.ts 1.6 KB
  - 📄 compressor.test.ts 14.5 KB
  - 📄 compressor.ts 42.5 KB
  - 📄 observer-pipeline.integration.test.ts 7.3 KB
  - 📄 observer.test.ts 11.7 KB
  - 📄 observer.ts 11.1 KB
  - 📄 reflection-service.test.ts 2.4 KB
  - 📄 reflection-service.ts 12.5 KB
  - 📄 reflector.test.ts 2.9 KB
  - 📄 reflector.ts 3.7 KB
  - 📄 router.test.ts 10.4 KB
  - 📄 router.ts 30.8 KB
  - 📄 session-parser.test.ts 3.5 KB
  - 📄 session-parser.ts 9.0 KB
  - 📄 watcher.test.ts 10.5 KB
  - 📄 watcher.ts 5.5 KB
- 📁 plugin/
  - 📄 slot.test.ts 2.2 KB
  - 📄 slot.ts 5.2 KB
- 📁 recall/
  - 📄 index.ts 236 B
  - 📄 service.test.ts 2.6 KB
  - 📄 service.ts 7.1 KB
  - 📄 strategies.test.ts 1.2 KB
  - 📄 strategies.ts 2.5 KB
  - 📄 types.ts 880 B
- 📁 replay/
  - 📁 normalizers/
    
    📄 chatgpt.ts 3.2 KB
    
    📄 claude.ts 3.0 KB
    
    📄 openclaw.ts 2.5 KB
    
    📄 opencode.ts 2.7 KB
  - 📄 types.ts 227 B
- 📁 test/
  - 📄 vitest.global-setup.ts 2.0 KB
  - 📄 vitest.setup.ts 304 B
- 📄 index.ts 13.1 KB
- 📄 openclaw-plugin.ts 621 B
- 📄 types.ts 7.0 KB
📁 templates/
- 📄 checkpoint.md 519 B
- 📄 daily-note.md 515 B
- 📄 daily.md 495 B
- 📄 decision.md 650 B
- 📄 handoff.md 511 B
- 📄 lesson.md 488 B
- 📄 person.md 634 B
- 📄 project.md 1.6 KB
- 📄 task.md 1.8 KB
📁 testdata/
- 📁 observer-benchmark/
  - 📁 client-meeting-commitments/
    
    📄 config.json 198 B
    
    📄 expected.md 546 B
    
    📄 transcript.md 486 B
  - 📁 coding-session-decisions/
    
    📄 config.json 165 B
    
    📄 expected.md 574 B
    
    📄 transcript.md 573 B
  - 📁 routine-maintenance-low-signal/
    
    📄 config.json 178 B
    
    📄 expected.md 113 B
    
    📄 transcript.md 337 B
📁 tests/
- 📁 compat-fixtures/
  - 📁 broken-openclaw-cli/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 134 B
    
    📄 HOOK.md 134 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 90 B
    
    📄 SKILL.md 48 B
  - 📁 broken-openclaw-signal/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 134 B
    
    📄 HOOK.md 134 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 90 B
    
    📄 SKILL.md 48 B
  - 📁 healthy/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 134 B
    
    📄 HOOK.md 134 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 90 B
    
    📄 SKILL.md 48 B
  - 📁 missing-events/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 134 B
    
    📄 HOOK.md 117 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 90 B
    
    📄 SKILL.md 48 B
  - 📁 missing-openclaw-cli/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 134 B
    
    📄 HOOK.md 134 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 90 B
    
    📄 SKILL.md 48 B
  - 📁 missing-package-hook/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 134 B
    
    📄 HOOK.md 134 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 71 B
    
    📄 SKILL.md 48 B
  - 📁 missing-requires-bin/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 134 B
    
    📄 HOOK.md 94 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 90 B
    
    📄 SKILL.md 48 B
  - 📁 missing-skill-file/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 134 B
    
    📄 HOOK.md 134 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 90 B
  - 📁 missing-skill-openclaw/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 134 B
    
    📄 HOOK.md 134 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 90 B
    
    📄 SKILL.md 35 B
  - 📁 non-auto-profile/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 138 B
    
    📄 HOOK.md 134 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 90 B
    
    📄 SKILL.md 48 B
  - 📁 unsafe-hook-handler/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 100 B
    
    📄 HOOK.md 134 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 90 B
    
    📄 SKILL.md 48 B
  - 📁 unsafe-shell-handler/
    
    📁 hooks/
    
    📁 clawvault/
    
    📄 handler.js 133 B
    
    📄 HOOK.md 134 B
    
    📄 openclaw.plugin.json 405 B
    
    📄 package.json 90 B
    
    📄 SKILL.md 48 B
  - 📄 cases.json 5.5 KB
  - 📄 README.md 620 B
- 📄 clawvault-hook-facts.test.js 6.7 KB
📄 .gitignore 398 B
📄 AGENT-TASK.md 2.8 KB
📄 AGENTS.md 1.7 KB
📄 CHANGELOG.md 22.2 KB
📄 openclaw.plugin.json 6.7 KB
📄 package-lock.json 246.1 KB
📄 package.json 3.5 KB
📄 PLAN.md 12.6 KB
📄 README.md 19.7 KB
📄 SECURITY.md 4.0 KB
📄 SKILL.md 11.7 KB
📄 tsconfig.json 481 B
📄 vitest.config.ts 198 B

SKILL.md

---
name: clawvault
version: "2.5.13"
description: Agent memory system with memory graph, context profiles, checkpoint/recover, structured storage, semantic search, and observational memory. Use when: storing/searching memories, preventing context death, graph-aware context retrieval, repairing broken sessions. Don't use when: general file I/O.
author: Versatly
source: https://github.com/Versatly/clawvault
repository: https://github.com/Versatly/clawvault
homepage: https://clawvault.dev
user-invocable: true
openclaw: {"emoji":"🐘","requires":{"bins":["clawvault","qmd"],"env":[]},"install":[{"id":"node","kind":"node","package":"clawvault","bins":["clawvault"],"label":"Install ClawVault CLI (npm)"},{"id":"qmd","kind":"node","package":"github:tobi/qmd","bins":["qmd"],"label":"Install qmd backend (required for query/context workflows)"}],"homepage":"https://clawvault.dev"}
metadata: {"openclaw":{"emoji":"🐘","requires":{"bins":["clawvault","qmd"],"env":[]},"install":[{"id":"node","kind":"node","package":"clawvault","bins":["clawvault"],"label":"Install ClawVault CLI (npm)"},{"id":"qmd","kind":"node","package":"github:tobi/qmd","bins":["qmd"],"label":"Install qmd backend (required for query/context workflows)"}],"homepage":"https://clawvault.dev"}}
---

# ClawVault 🐘

An elephant never forgets. Structured memory for OpenClaw agents.

> **Built for [OpenClaw](https://openclaw.ai)**. Canonical install: npm CLI + hook install + hook enable.

## Security & Transparency

**What this skill does:**
- Reads/writes markdown files in your vault directory (`CLAWVAULT_PATH` or auto-discovered)
- `repair-session` reads and modifies OpenClaw session transcripts (`~/.openclaw/agents/`) — creates backups before writing
- Provides an OpenClaw **hook pack** (`hooks/clawvault/handler.js`) with lifecycle events (`gateway:startup`, `gateway:heartbeat`, `command:new`, `session:start`, `compaction:memoryFlush`, `cron.weekly`). Hook is opt-in and must be installed/enabled.
- `observe --compress` makes LLM API calls (Gemini Flash by default) to compress session transcripts into observations

**Environment variables used:**
- `CLAWVAULT_PATH` — vault location (optional, auto-discovered if not set)
- `OPENCLAW_HOME` / `OPENCLAW_STATE_DIR` — used by `repair-session` to find session transcripts
- `GEMINI_API_KEY` — used by `observe` for LLM compression (optional, only if using observe features)

**No cloud sync — all data stays local. No network calls except LLM API for observe compression.**

**This is a full CLI tool, not instruction-only.** It writes files, registers hooks, and runs code.

**Auditability:** the published ClawHub skill bundle includes `SKILL.md`, `HOOK.md`, and `hooks/clawvault/handler.js` so users can inspect hook behavior before enabling it.

## Install (Canonical)

```bash
npm install -g clawvault
openclaw hooks install clawvault
openclaw hooks enable clawvault

# Verify and reload
openclaw hooks list --verbose
openclaw hooks info clawvault
openclaw hooks check
# restart gateway process
```

`clawhub install clawvault` can install skill guidance, but does not replace explicit hook pack installation.

### Recommended Safe Install Flow

```bash
# 1) Review package metadata before install
npm view clawvault version dist.integrity dist.tarball repository.url

# 2) Install CLI + qmd dependency
npm install -g clawvault@latest
npm install -g github:tobi/qmd

# 3) Install hook pack, but DO NOT enable yet
openclaw hooks install clawvault

# 4) Review hook source locally before enabling
node -e "const fs=require('fs');const p='hooks/clawvault/handler.js';console.log(fs.existsSync(p)?p:'hook file not found in current directory')"
openclaw hooks info clawvault

# 5) Enable only after review
openclaw hooks enable clawvault
openclaw hooks check
```

## Setup

```bash
# Initialize vault (creates folder structure + templates)
clawvault init ~/my-vault

# Or set env var to use existing vault
export CLAWVAULT_PATH=/path/to/memory

# Optional: shell integration (aliases + CLAWVAULT_PATH)
clawvault shell-init >> ~/.bashrc
```

## Quick Start for New Agents

```bash
# Start your session (recover + recap + summary)
clawvault wake

# Capture and checkpoint during work
clawvault capture "TODO: Review PR tomorrow"
clawvault checkpoint --working-on "PR review" --focus "type guards"

# End your session with a handoff
clawvault sleep "PR review + type guards" --next "respond to CI" --blocked "waiting for CI"

# Health check when something feels off
clawvault doctor
```

## Reality Checks Before Use

```bash
# Verify runtime compatibility with current OpenClaw setup
clawvault compat

# Verify qmd is available
qmd --version

# Verify OpenClaw CLI is installed in this shell
openclaw --version
```

ClawVault currently depends on `qmd` for core vault/query flows.

## Current Feature Set

### Memory Graph

ClawVault builds a typed knowledge graph from wiki-links, tags, and frontmatter:

```bash
# View graph summary
clawvault graph

# Refresh graph index
clawvault graph --refresh
```

Graph is stored at `.clawvault/graph-index.json` — schema versioned, incremental rebuild.

### Graph-Aware Context Retrieval

```bash
# Default context (semantic + graph neighbors)
clawvault context "database decision"

# With a profile preset
clawvault context --profile planning "Q1 roadmap"
clawvault context --profile incident "production outage"
clawvault context --profile handoff "session end"

# Auto profile (used by OpenClaw hook)
clawvault context --profile auto "current task"
```

### Context Profiles

| Profile | Purpose |
|---------|---------|
| `default` | Balanced retrieval |
| `planning` | Broader strategic context |
| `incident` | Recent events, blockers, urgent items |
| `handoff` | Session transition context |
| `auto` | Hook-selected profile based on session intent |

### OpenClaw Compatibility Diagnostics

```bash
# Check hook wiring, event routing, handler safety
clawvault compat

# Strict mode for CI
clawvault compat --strict
```

## Core Commands

### Wake + Sleep (primary)

```bash
clawvault wake
clawvault sleep "what I was working on" --next "ship v1" --blocked "waiting for API key"
```

### Store memories by type

```bash
# Types: fact, feeling, decision, lesson, commitment, preference, relationship, project
clawvault remember decision "Use Postgres over SQLite" --content "Need concurrent writes for multi-agent setup"
clawvault remember lesson "Context death is survivable" --content "Checkpoint before heavy work"
clawvault remember relationship "Justin Dukes" --content "Client contact at Hale Pet Door"
```

### Quick capture to inbox

```bash
clawvault capture "TODO: Review PR tomorrow"
```

### Search (requires qmd installed)

```bash
# Keyword search (fast)
clawvault search "client contacts"

# Semantic search (slower, more accurate)
clawvault vsearch "what did we decide about the database"
```

## Context Death Resilience

### Wake (start of session)

```bash
clawvault wake
```

### Sleep (end of session)

```bash
clawvault sleep "what I was working on" --next "finish docs" --blocked "waiting for review"
```

### Checkpoint (save state frequently)

```bash
clawvault checkpoint --working-on "PR review" --focus "type guards" --blocked "waiting for CI"
```

### Recover (manual check)

```bash
clawvault recover --clear
# Shows: death time, last checkpoint, recent handoff
```

### Handoff (manual session end)

```bash
clawvault handoff \
  --working-on "ClawVault improvements" \
  --blocked "npm token" \
  --next "publish to npm, create skill" \
  --feeling "productive"
```

### Recap (bootstrap new session)

```bash
clawvault recap
# Shows: recent handoffs, active projects, pending commitments, lessons
```

## Auto-linking

Wiki-link entity mentions in markdown files:

```bash
# Link all files
clawvault link --all

# Link single file
clawvault link memory/2024-01-15.md
```

## Folder Structure

```
vault/
├── .clawvault/           # Internal state
│   ├── last-checkpoint.json
│   └── dirty-death.flag
├── decisions/            # Key choices with reasoning
├── lessons/              # Insights and patterns
├── people/               # One file per person
├── projects/             # Active work tracking
├── handoffs/             # Session continuity
├── inbox/                # Quick captures
└── templates/            # Document templates
```

## Best Practices

1. **Wake at session start** — `clawvault wake` restores context
2. **Checkpoint every 10-15 min** during heavy work
3. **Sleep before session end** — `clawvault sleep` captures next steps
4. **Use types** — knowing WHAT you're storing helps WHERE to put it
5. **Wiki-link liberally** — `[[person-name]]` builds your knowledge graph

## Checklist for AGENTS.md

```markdown
## Memory Checklist
- [ ] Run `clawvault wake` at session start
- [ ] Checkpoint during heavy work
- [ ] Capture key decisions/lessons with `clawvault remember`
- [ ] Use wiki-links like `[[person-name]]`
- [ ] End with `clawvault sleep "..." --next "..." --blocked "..."`
- [ ] Run `clawvault doctor` when something feels off
```

Append this checklist to existing memory instructions. Do not replace your full AGENTS.md behavior unless you intend to.

## Session Transcript Repair (v1.5.0+)

When the Anthropic API rejects with "unexpected tool_use_id found in tool_result blocks", use:

```bash
# See what's wrong (dry-run)
clawvault repair-session --dry-run

# Fix it
clawvault repair-session

# Repair a specific session
clawvault repair-session --session <id> --agent <agent-id>

# List available sessions
clawvault repair-session --list
```

**What it fixes:**
- Orphaned `tool_result` blocks referencing non-existent `tool_use` IDs
- Aborted tool calls with partial JSON
- Broken parent chain references

Backups are created automatically (use `--no-backup` to skip).

## Troubleshooting

- **qmd not installed** — install qmd, then confirm with `qmd --version`
- **No ClawVault found** — run `clawvault init` or set `CLAWVAULT_PATH`
- **CLAWVAULT_PATH missing** — run `clawvault shell-init` and add to shell rc
- **Too many orphan links** — run `clawvault link --orphans`
- **Inbox backlog warning** — process or archive inbox items
- **"unexpected tool_use_id" error** — run `clawvault repair-session`
- **OpenClaw integration drift** — run `clawvault compat`
- **Hook enable fails / hook not found** — run `openclaw hooks install clawvault`, then `openclaw hooks enable clawvault`, restart gateway, and verify via `openclaw hooks list --verbose`
- **Graph out of date** — run `clawvault graph --refresh`
- **Wrong context for task** — try `clawvault context --profile incident` or `--profile planning`

## Stability Snapshot

- Typecheck passes (`npm run typecheck`)
- Test suite passes (`449/449`)
- Cross-platform path handling hardened for Windows in:
  - qmd URI/document path normalization
  - WebDAV path safety and filesystem resolution
  - shell-init output expectations
- OpenClaw runtime wiring validated by `clawvault compat --strict` (requires local `openclaw` binary for full runtime validation)

## Integration with qmd

ClawVault uses [qmd](https://github.com/tobi/qmd) for search:

```bash
# Install qmd
bun install -g github:tobi/qmd

# Alternative
npm install -g github:tobi/qmd

# Add vault as collection
qmd collection add /path/to/vault --name my-memory --mask "**/*.md"

# Update index
qmd update && qmd embed
```

## Environment Variables

- `CLAWVAULT_PATH` — Default vault path (skips auto-discovery)
- `OPENCLAW_HOME` — OpenClaw home directory (used by repair-session)
- `OPENCLAW_STATE_DIR` — OpenClaw state directory (used by repair-session)
- `GEMINI_API_KEY` — Used by `observe` for LLM-powered compression (optional)

## Links

- npm: https://www.npmjs.com/package/clawvault
- GitHub: https://github.com/Versatly/clawvault
- Issues: https://github.com/Versatly/clawvault/issues

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

clawvault

Directory Structure

SKILL.md

Report

Notice