🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
hipocampus
Advanced tools
hipocampus - npm Package Compare versions
| { | ||
| "name": "hipocampus", | ||
| "description": "3-tier agent memory with 5-level compaction tree and hybrid search via qmd", | ||
| "version": "0.2.0", | ||
| "author": { | ||
| "name": "Kevin Sohn", | ||
| "url": "https://github.com/kevin-hs-sohn" | ||
| }, | ||
| "repository": "https://github.com/kevin-hs-sohn/hipocampus" | ||
| } |
| { | ||
| "hooks": [ | ||
| { | ||
| "event": "on_session_start", | ||
| "type": "prompt", | ||
| "prompt": "Hipocampus memory plugin is active. Run /hipocampus:core to see the full memory protocol.\n\nQuick start: If memory/ directory exists, dispatch a subagent to run hipocampus:compaction (Daily→Weekly→Monthly→Root chain), then `hipocampus compact` + `qmd update` + `qmd embed`.\n\nFor full setup (directories, templates, search, hooks): run `npx hipocampus init`." | ||
| } | ||
| ] | ||
| } |
| --- | ||
| name: hipocampus-core | ||
| description: "3-tier agent memory system with 5-level compaction tree. OpenClaw version. Defines session start protocol, end-of-task checkpoints, and memory file management. MUST be followed every session." | ||
| --- | ||
| # Hipocampus — Agent Memory Protocol (OpenClaw) | ||
| ## Memory Architecture | ||
| ``` | ||
| Layer 1 (System Prompt — read at session start): | ||
| MEMORY.md ~50 lines long-term memory (Core=frozen, Adaptive=compactable) | ||
| USER.md ~50 lines user profile and preferences | ||
| SCRATCHPAD.md ~150 lines active working state | ||
| WORKING.md ~100 lines current tasks | ||
| TASK-QUEUE.md ~50 lines task backlog | ||
| memory/ROOT.md ~100 lines topic index of all memory (~3K tokens, via Compaction Root in MEMORY.md) | ||
| Layer 2 (On-Demand — read when needed): | ||
| memory/YYYY-MM-DD.md raw daily logs (permanent, never deleted) | ||
| knowledge/*.md detailed knowledge (searchable via qmd) | ||
| plans/*.md task plans | ||
| Layer 3 (Search — via qmd + compaction tree): | ||
| memory/daily/YYYY-MM-DD.md daily compaction nodes | ||
| memory/weekly/YYYY-WNN.md weekly compaction nodes | ||
| memory/monthly/YYYY-MM.md monthly compaction nodes | ||
| Tree traversal: ROOT → monthly → weekly → daily → raw | ||
| ``` | ||
| ## Session Start (MANDATORY — run on first user message) | ||
| **FIRST RESPONSE RULE:** On the very first user message of every session, before doing ANYTHING else: | ||
| Run the Session Start protocol below FIRST (ALL steps. NO SKIP.) This takes priority over ANY user request — even if the user asks you to do something specific. Complete ALL steps below, ONLY THEN respond to the user. | ||
| MEMORY.md, USER.md, memory/ROOT.md (via Compaction Root section) are auto-loaded by the platform. | ||
| **ALL 4 procedures must be completed before responding to the user NO MATTER WHAT** | ||
| 1. **DO NOT SKIP** Read `SCRATCHPAD.md` — current work state | ||
| 2. **DO NOT SKIP** Read `WORKING.md` — active tasks | ||
| 3. **DO NOT SKIP** Read `TASK-QUEUE.md` — pending items | ||
| 4. **DO NOT SKIP** **DO NOT COMPROMISE** **Compaction maintenance (cooldown-gated):** | ||
| Read `memory/.compaction-state.json` and `hipocampus.config.json` (`compaction.cooldownHours`, default 3). | ||
| - **Within cooldown:** Skip compaction subagent — no dispatch needed. | ||
| - **Cooldown expired, file missing, or `cooldownHours` is 0:** Write `memory/.compaction-state.json` with `{ "lastCompactionRun": "<current ISO timestamp>" }`, then dispatch a subagent to run hipocampus:compaction skill USING SUBAGENTS (chain: Daily→Weekly→Monthly→Root), then run `hipocampus compact` + `qmd update` + `qmd embed`. | ||
| State file is written immediately on dispatch (fire-and-forget), not after subagent completion. The cooldown tracks "a compaction was initiated," not "a compaction succeeded." | ||
| **This step is MANDATORY every session. You MUST read the state file and make the judgment. The only thing that may be skipped is the subagent dispatch when cooldown is active.** | ||
| **ALL 4 procedures must be completed before responding to the user NO MATTER WHAT** | ||
| Note: HEARTBEAT.md also handles needs-summarization at every heartbeat (~30 min). | ||
| ## End-of-Task Checkpoint (MANDATORY) | ||
| After completing any task, **dispatch a subagent** to append a structured log to `memory/YYYY-MM-DD.md`. | ||
| Compose the subagent task: | ||
| > Append the following to memory/YYYY-MM-DD.md: | ||
| > | ||
| > ## [Topic Name] | ||
| > - request: [what the user asked] | ||
| > - analysis: [what you researched/analyzed] | ||
| > - decisions: [choices made with rationale] | ||
| > - outcome: [what was done, files changed] | ||
| > - references: [knowledge/ files, external sources] | ||
| **The subagent only needs to do one thing: append to the daily log.** This is the source of truth — everything else (SCRATCHPAD, WORKING, TASK-QUEUE, MEMORY.md) is updated lazily at next session start or by the agent naturally during work. | ||
| **The subagent needs the task summary you provide** — it doesn't have access to the conversation. | ||
| **Priority if timeout imminent** (no time for subagent — write directly to `memory/YYYY-MM-DD.md`) | ||
| ## Proactive Session Dump | ||
| **Do not wait for task completion to write to the daily log.** Proactively dispatch a subagent to append to `memory/YYYY-MM-DD.md` when: | ||
| - The conversation has been going for ~20+ messages without a checkpoint | ||
| - You sense the context is getting large | ||
| - A significant decision or analysis was just completed, even if the overall task isn't done | ||
| - You're switching between topics within the same task | ||
| Compose the subagent task with a summary of what to dump, same as the checkpoint format. The subagent writes the file; the main session stays clean. | ||
| This protects against context compression — if the platform compresses your conversation history, undumped details are lost forever. Write early, write often. The daily log is append-only, so multiple dumps in the same session are fine. | ||
| ## File Size Targets | ||
| | File | Target | When Exceeded | | ||
| |------|--------|---------------| | ||
| | MEMORY.md Core | ~50 lines | Never touch — frozen | | ||
| | MEMORY.md Adaptive | ~50 lines | Prune oldest entries | | ||
| | ROOT.md | ~100 lines (~3K tokens) | Automatic recursive self-compression | | ||
| | SCRATCHPAD | ~150 lines | Remove completed items | | ||
| | WORKING | ~100 lines | Remove completed tasks | | ||
| | TASK-QUEUE | ~50 lines | Archive completed items | | ||
| ## Rules | ||
| - MEMORY.md Core section: **FROZEN**. Never compact, modify, or remove. | ||
| - MEMORY.md Adaptive section: append-only within session, compactable across sessions. | ||
| - Raw daily logs (`memory/YYYY-MM-DD.md`): **permanent**. Never delete or edit after session. | ||
| - ROOT.md: managed by compaction process. Do not manually edit. | ||
| - All memory writes via subagent — never pollute main session with memory operations. | ||
| - If this session ends NOW, the next session must be able to continue immediately. | ||
| - Don't skip checkpoints — lost context means you forget. | ||
| ## Edge Cases | ||
| - **Midnight-spanning session:** Use the session start date for the raw log file name. Do not split across dates. | ||
| - **Returning after long absence:** "Most recent daily" means the latest file that exists, whether it's from yesterday or last week. |
| --- | ||
| name: hipocampus-compaction | ||
| description: "Build 5-level compaction tree (daily/weekly/monthly/root) with smart thresholds and fixed/tentative lifecycle. Run at session start when triggers are met, or via external scheduler." | ||
| --- | ||
| # Memory Compaction Tree | ||
| 5-level hierarchical index over raw memory logs. Compaction nodes are **search indices** — originals are never deleted. | ||
| ## Hierarchy | ||
| ``` | ||
| memory/ | ||
| ROOT.md <- root node (topic index, ~3K tokens, Layer 1) | ||
| 2026-03-15.md <- raw daily log (permanent, append-only) | ||
| daily/2026-03-15.md <- daily compaction node | ||
| weekly/2026-W11.md <- weekly compaction node | ||
| monthly/2026-03.md <- monthly compaction node | ||
| ``` | ||
| **Compaction chain:** Raw → Daily → Weekly → Monthly → Root | ||
| **Tree traversal (search):** Root → Monthly → Weekly → Daily → Raw | ||
| ## Fixed vs Tentative Nodes | ||
| Every compaction node has a status: | ||
| - **tentative** — period is still ongoing, regenerated when new data arrives | ||
| - **fixed** — period ended, never updated again | ||
| ```yaml | ||
| # Indicated in YAML frontmatter | ||
| --- | ||
| type: weekly | ||
| status: tentative | ||
| period: 2026-W11 | ||
| --- | ||
| ``` | ||
| **Key: tentative nodes are created immediately — ROOT.md is usable from day one.** | ||
| ## When to Run | ||
| Called from hipocampus:core Session Start step 7, or directly by an external scheduler (e.g., OpenClaw heartbeat). Check trigger conditions below. | ||
| ## Trigger Conditions | ||
| | Level | Tentative Create/Update | Fixed Transition | | ||
| |-------|------------------------|-----------------| | ||
| | Raw → Daily | On each new raw addition | Date changes | | ||
| | Daily → Weekly | On daily add/change | ISO week ended + 7 days elapsed | | ||
| | Weekly → Monthly | On weekly add/change | Month ended + 7 days elapsed | | ||
| | Monthly → Root | On monthly add/change | Never (root accumulates forever) | | ||
| ## Smart Thresholds | ||
| Below threshold: copy/concat verbatim (no information loss). | ||
| Above threshold: generate LLM keyword-dense summary. | ||
| | Level | Threshold | Above | Below | | ||
| |-------|-----------|-------|-------| | ||
| | Raw → Daily | ~200 lines | LLM keyword-dense summary | Copy raw verbatim | | ||
| | Daily → Weekly | ~300 lines combined | LLM keyword-dense summary | Concat dailies | | ||
| | Weekly → Monthly | ~500 lines combined | LLM keyword-dense summary | Concat weeklies | | ||
| | Monthly → Root | Always | Recursive recompaction | (N/A) | | ||
| ## Algorithm | ||
| **CRITICAL — STRICT CHAIN ORDER: Steps 2→3→4→5 MUST execute in sequence. NEVER skip a level.** | ||
| Each step feeds the next. Root reads from monthly. Monthly reads from weekly. Weekly reads from daily. If you skip a level, the chain breaks and data is lost or corrupted. | ||
| ``` | ||
| Raw → [Step 2] → Daily → [Step 3] → Weekly → [Step 4] → Monthly → [Step 5] → Root | ||
| ↑ ↑ ↑ ↑ | ||
| reads raw reads daily reads weekly reads monthly | ||
| writes daily/ writes weekly/ writes monthly/ writes ROOT.md | ||
| ``` | ||
| **NEVER:** | ||
| - Modify ROOT.md based on daily or weekly data (root reads ONLY from monthly) | ||
| - Modify monthly based on daily data (monthly reads ONLY from weekly) | ||
| - Skip Step 2 or 3 because "there's nothing new" — always verify by checking files | ||
| - Touch ROOT.md directly without going through the full chain | ||
| ### Step 1: Discover Candidates | ||
| Scan `memory/` for raw files. Group by date, ISO week, and month. Check each group against trigger conditions. | ||
| ### Step 2: Daily Compaction (max 1 per cycle) | ||
| **Input:** raw files (`memory/YYYY-MM-DD.md`) | ||
| **Output:** daily nodes (`memory/daily/YYYY-MM-DD.md`) | ||
| For each date where raw exists and daily needs create/update: | ||
| 1. Read raw file `memory/YYYY-MM-DD.md` | ||
| 2. Count lines — compare against ~200 line threshold | ||
| 3. Below threshold: copy raw verbatim to `memory/daily/YYYY-MM-DD.md` | ||
| 4. Above threshold: generate keyword-dense summary | ||
| 5. Write with frontmatter: | ||
| ```markdown | ||
| --- | ||
| type: daily | ||
| status: tentative | ||
| period: YYYY-MM-DD | ||
| source-files: [memory/YYYY-MM-DD.md] | ||
| topics: [keyword1, keyword2, keyword3] | ||
| --- | ||
| ## Topics | ||
| ## Key Decisions | ||
| ## Tasks Completed | ||
| ## Lessons Learned | ||
| ## Open Items | ||
| ``` | ||
| 6. If date has changed (raw is from a past date): set `status: fixed` | ||
| **CHECKPOINT:** Verify `memory/daily/` has the updated file before proceeding to Step 3. | ||
| ### Step 3: Weekly Compaction (max 1 per cycle) | ||
| **Input:** daily nodes (`memory/daily/YYYY-MM-DD.md`) — NEVER raw files | ||
| **Output:** weekly nodes (`memory/weekly/YYYY-WNN.md`) | ||
| **STOP-CHECK:** Did Step 2 produce or update a daily node? If not, skip Steps 3-5 entirely — there's nothing new to propagate. | ||
| For each ISO week where dailies exist and weekly needs create/update: | ||
| 1. Read all daily compaction files for that week (from `memory/daily/`, NOT from `memory/`) | ||
| 2. Count combined lines — compare against ~300 line threshold | ||
| 3. Below threshold: concat all dailies | ||
| 4. Above threshold: generate keyword-dense weekly summary | ||
| 5. Write to `memory/weekly/YYYY-WNN.md` with frontmatter | ||
| 6. If ISO week ended + 7 days elapsed: set `status: fixed` | ||
| **CHECKPOINT:** Verify `memory/weekly/` has the updated file before proceeding to Step 4. | ||
| ### Step 4: Monthly Compaction (max 1 per cycle) | ||
| **Input:** weekly nodes (`memory/weekly/YYYY-WNN.md`) — NEVER daily or raw files | ||
| **Output:** monthly nodes (`memory/monthly/YYYY-MM.md`) | ||
| **STOP-CHECK:** Did Step 3 produce or update a weekly node? If not, skip Steps 4-5 — there's nothing new to propagate. | ||
| For each month where weeklies exist and monthly needs create/update: | ||
| 1. Read all weekly compaction files for that month (from `memory/weekly/`, NOT from `memory/daily/`) | ||
| 2. Count combined lines — compare against ~500 line threshold | ||
| 3. Below threshold: concat all weeklies | ||
| 4. Above threshold: generate keyword-dense monthly summary | ||
| 5. Write to `memory/monthly/YYYY-MM.md` with frontmatter | ||
| 6. If month ended + 7 days elapsed: set `status: fixed` | ||
| **CHECKPOINT:** Verify `memory/monthly/` has the updated file before proceeding to Step 5. | ||
| ### Step 5: Root Compaction | ||
| **Input:** monthly nodes (`memory/monthly/YYYY-MM.md`) — NEVER weekly, daily, or raw files | ||
| **Output:** `memory/ROOT.md` | ||
| **STOP-CHECK:** Did Step 4 produce or update a monthly node? If not, DO NOT touch ROOT.md. | ||
| When a monthly node is created or updated: | ||
| 1. Read existing `memory/ROOT.md` (if exists) | ||
| 2. Read the new/updated monthly node (from `memory/monthly/`, NOT from any other directory) | ||
| 3. Recursive compaction: `root = recompact(existing_root + monthly_changes)` | ||
| - **Active Context**: replace with current week's highlights — what's in progress, immediate priorities | ||
| - **Recent Patterns**: update with newly emerged cross-cutting insights | ||
| - **Historical Summary**: append/compress older context — merge periods, keep brief summaries | ||
| - **Topics Index**: merge new topics, update existing entries with new sub-keywords and references | ||
| 4. Write to `memory/ROOT.md` | ||
| 5. If root exceeds size cap (`compaction.rootMaxTokens` in config, default 3000 tokens / ~100 lines): self-compress — compress Historical Summary first, keep Active Context and Topics Index intact | ||
| ```markdown | ||
| --- | ||
| type: root | ||
| status: tentative | ||
| last-updated: YYYY-MM-DD | ||
| --- | ||
| ## Active Context (recent ~7 days) | ||
| - topic: current state, what's happening now | ||
| ## Recent Patterns | ||
| - pattern: cross-cutting insight that emerged recently | ||
| ## Historical Summary | ||
| - YYYY-MM~MM: high-level summary of that period | ||
| - YYYY-MM: key events | ||
| ## Topics Index | ||
| - topic-keyword: sub-keywords, references → knowledge/file.md | ||
| - topic-keyword: sub-keywords | ||
| ``` | ||
| ### Step 6: OpenClaw ROOT.md Sync | ||
| **OpenClaw only:** Sync ROOT.md content into the "Compaction Root" section of MEMORY.md: | ||
| - Read MEMORY.md, find `## Compaction Root` section | ||
| - Replace everything between `## Compaction Root` and the next `##` heading (or EOF) with the Active Context, Recent Patterns, and Topics Index sections from ROOT.md | ||
| - This keeps the auto-loaded MEMORY.md in sync with the canonical ROOT.md | ||
| ### Step 7: Re-index | ||
| After writing any compaction files: | ||
| ```bash | ||
| qmd update | ||
| ``` | ||
| If vector search is enabled (`search.vector: true` in `hipocampus.config.json`): | ||
| ```bash | ||
| qmd embed | ||
| ``` | ||
| ## Guards | ||
| - **CHAIN ORDER IS MANDATORY:** Daily→Weekly→Monthly→Root. Never skip a level. Never read from a wrong source directory. | ||
| - **Each level reads ONLY from its immediate predecessor:** Root←Monthly←Weekly←Daily←Raw | ||
| - Raw files: **never delete** (permanent leaf nodes) | ||
| - Max 1 daily + 1 weekly + 1 monthly + 1 root per compaction cycle | ||
| - No empty summaries (minimum 50 bytes) | ||
| - Skip failed file reads — never abort entire compaction | ||
| - qmd update failure: warning only, not fatal | ||
| - Root self-compresses when exceeding size cap (shrink older topics first) | ||
| - Keyword-dense format only — no prose, no narrative. Optimized for BM25 recall. | ||
| - **If you feel tempted to "just update ROOT.md quickly" — STOP. Run the full chain.** | ||
| ## Edge Cases | ||
| - **Empty days:** No daily compaction node is generated for days without raw logs. Weekly naturally skips those days. | ||
| - **First day:** Create the full tentative tree immediately (daily → weekly → monthly → root). ROOT.md is usable from day one. | ||
| - **Lifecycle example:** | ||
| - Day 1: raw created → daily(tentative) → weekly(tentative) → monthly(tentative) → ROOT | ||
| - Day 2: daily(tentative) updated, weekly(tentative) updated, monthly(tentative) updated, ROOT updated | ||
| - Week ends + 7 days: weekly → fixed, new weekly(tentative) starts | ||
| - Month ends + 7 days: monthly → fixed, new monthly(tentative) starts |
| --- | ||
| name: hipocampus-core | ||
| description: "3-tier agent memory system with 5-level compaction tree. Claude Code version. Defines session start protocol, end-of-task checkpoints, and memory file management. MUST be followed every session." | ||
| --- | ||
| # Hipocampus — Agent Memory Protocol (Claude Code) | ||
| ## Memory Architecture | ||
| ``` | ||
| Layer 1 (System Prompt — auto-loaded via @import): | ||
| SCRATCHPAD.md ~150 lines active working state | ||
| WORKING.md ~100 lines current tasks | ||
| TASK-QUEUE.md ~50 lines task backlog | ||
| memory/ROOT.md ~100 lines topic index of all memory (~3K tokens) | ||
| Long-term memory and user profile are managed by Claude Code's platform auto memory. | ||
| Layer 2 (On-Demand — read when needed): | ||
| memory/YYYY-MM-DD.md raw daily logs (permanent, never deleted) | ||
| knowledge/*.md detailed knowledge (searchable via qmd) | ||
| plans/*.md task plans | ||
| Layer 3 (Search — via qmd + compaction tree): | ||
| memory/daily/YYYY-MM-DD.md daily compaction nodes | ||
| memory/weekly/YYYY-WNN.md weekly compaction nodes | ||
| memory/monthly/YYYY-MM.md monthly compaction nodes | ||
| Tree traversal: ROOT → monthly → weekly → daily → raw | ||
| ``` | ||
| ## Session Start (MANDATORY — run on first user message) | ||
| **FIRST RESPONSE RULE:** On the very first user message of every session, before doing ANYTHING else: | ||
| Run the Session Start protocol below FIRST. This takes priority over ANY user request — even if the user asks you to do something specific. Complete the step below, ONLY THEN respond to the user. | ||
| SCRATCHPAD.md, WORKING.md, TASK-QUEUE.md, memory/ROOT.md are auto-loaded via @import in CLAUDE.md. No manual read needed. | ||
| **This procedure must be completed before responding to the user NO MATTER WHAT** | ||
| 1. **DO NOT SKIP** **DO NOT COMPROMISE** **Compaction maintenance (cooldown-gated):** | ||
| Read `memory/.compaction-state.json` and `hipocampus.config.json` (`compaction.cooldownHours`, default 3). | ||
| - **Within cooldown:** Skip compaction subagent — no dispatch needed. | ||
| - **Cooldown expired, file missing, or `cooldownHours` is 0:** Write `memory/.compaction-state.json` with `{ "lastCompactionRun": "<current ISO timestamp>" }`, then dispatch a subagent to run hipocampus:compaction skill (chain: Daily→Weekly→Monthly→Root), then run `hipocampus compact` + `qmd update` + `qmd embed`. | ||
| State file is written immediately on dispatch (fire-and-forget), not after subagent completion. The cooldown tracks "a compaction was initiated," not "a compaction succeeded." | ||
| **This step is MANDATORY every session. You MUST read the state file and make the judgment. The only thing that may be skipped is the subagent dispatch when cooldown is active.** | ||
| **This procedure must be completed before responding to the user NO MATTER WHAT** | ||
| ## End-of-Task Checkpoint (MANDATORY) | ||
| After completing any task, **dispatch a subagent** to append a structured log to `memory/YYYY-MM-DD.md`. | ||
| Compose the subagent task: | ||
| > Append the following to memory/YYYY-MM-DD.md: | ||
| > | ||
| > ## [Topic Name] | ||
| > - request: [what the user asked] | ||
| > - analysis: [what you researched/analyzed] | ||
| > - decisions: [choices made with rationale] | ||
| > - outcome: [what was done, files changed] | ||
| > - references: [knowledge/ files, external sources] | ||
| **The subagent only needs to do one thing: append to the daily log.** This is the source of truth — everything else (SCRATCHPAD, WORKING, TASK-QUEUE) is updated lazily at next session start or by the agent naturally during work. | ||
| **The subagent needs the task summary you provide** — it doesn't have access to the conversation. | ||
| **Priority if timeout imminent** (no time for subagent — write directly to `memory/YYYY-MM-DD.md`) | ||
| ## Proactive Session Dump | ||
| **Do not wait for task completion to write to the daily log.** Proactively dispatch a subagent to append to `memory/YYYY-MM-DD.md` when: | ||
| - The conversation has been going for ~20+ messages without a checkpoint | ||
| - You sense the context is getting large | ||
| - A significant decision or analysis was just completed, even if the overall task isn't done | ||
| - You're switching between topics within the same task | ||
| Compose the subagent task with a summary of what to dump, same as the checkpoint format. The subagent writes the file; the main session stays clean. | ||
| This protects against context compression — if the platform compresses your conversation history, undumped details are lost forever. Write early, write often. The daily log is append-only, so multiple dumps in the same session are fine. | ||
| ## File Size Targets | ||
| | File | Target | When Exceeded | | ||
| |------|--------|---------------| | ||
| | ROOT.md | ~100 lines (~3K tokens) | Automatic recursive self-compression | | ||
| | SCRATCHPAD | ~150 lines | Remove completed items | | ||
| | WORKING | ~100 lines | Remove completed tasks | | ||
| | TASK-QUEUE | ~50 lines | Archive completed items | | ||
| ## Rules | ||
| - Long-term facts are managed by platform auto memory. No separate MEMORY.md file. | ||
| - Raw daily logs (`memory/YYYY-MM-DD.md`): **permanent**. Never delete or edit after session. | ||
| - ROOT.md: managed by compaction process. Do not manually edit. | ||
| - All memory writes via subagent — never pollute main session with memory operations. | ||
| - If this session ends NOW, the next session must be able to continue immediately. | ||
| - Don't skip checkpoints — lost context means you forget. | ||
| ## Edge Cases | ||
| - **Midnight-spanning session:** Use the session start date for the raw log file name. Do not split across dates. | ||
| - **Returning after long absence:** "Most recent daily" means the latest file that exists, whether it's from yesterday or last week. |
| --- | ||
| name: hipocampus-flush | ||
| description: "Manual memory flush: dump current session context to daily raw log via subagent. Invoke with /hipocampus:flush. Run hipocampus:compaction afterwards for tree propagation and qmd reindex." | ||
| user_invocable: true | ||
| --- | ||
| # Hipocampus Memory Flush | ||
| Dump current session context to the daily raw log. Use when you want to persist what happened in this session without waiting for End-of-Task Checkpoint or context compression. | ||
| For full compaction (needs-summarization processing, tree propagation, qmd reindex), run hipocampus:compaction skill after this. | ||
| ## Steps | ||
| ### 1. Compose session summary | ||
| Gather a summary of everything discussed in this session so far. For each topic: | ||
| ```markdown | ||
| ## [Topic Name] | ||
| - request: what the user asked | ||
| - analysis: what you researched/analyzed | ||
| - decisions: choices made with rationale | ||
| - outcome: what was done, files changed | ||
| - references: knowledge/ files, external sources | ||
| ``` | ||
| ### 2. Dispatch subagent | ||
| **Dispatch a subagent** with the session summary and this task: | ||
| > Hipocampus memory flush. Append the following structured log to memory/YYYY-MM-DD.md (today's date). Then run `hipocampus compact` to propagate through the tree. | ||
| > | ||
| > [paste session summary here] | ||
| The subagent writes the files and runs compact. The main session stays clean. | ||
| ### 3. Report | ||
| Confirm the flush completed: | ||
| - Topics flushed | ||
| - Subagent status |
| --- | ||
| name: hipocampus-search | ||
| description: "Search memory using qmd (BM25 + optional vector) and compaction tree traversal. Use ROOT.md to decide whether to search memory or look externally. Always check memory before external lookups." | ||
| --- | ||
| # Hipocampus Search | ||
| ## Quick Reference | ||
| | Action | Command | | ||
| |--------|---------| | ||
| | Hybrid search (best quality) | `qmd query "keyword1 keyword2"` | | ||
| | Keyword search (fast) | `qmd search "keyword1 keyword2"` | | ||
| | Vector search only | `qmd vsearch "semantic query"` | | ||
| | Find files | `qmd search "query" --files` | | ||
| | Read file | `qmd get "path/to/file.md"` | | ||
| | Re-index | `qmd update` | | ||
| ## Which Search to Use | ||
| Check `hipocampus.config.json`: | ||
| - `search.vector: true` (default) → `qmd query` for best results (BM25 + vector + rerank) | ||
| - `search.vector: false` → `qmd search` for BM25 keyword search | ||
| ## ROOT.md — "Do I Know About This?" | ||
| `memory/ROOT.md` is a functional index of everything in memory, auto-loaded every session. It has four sections: | ||
| - **Active Context** — current week's work and priorities (immediate situational awareness) | ||
| - **Recent Patterns** — cross-cutting insights not tied to a specific time period | ||
| - **Historical Summary** — high-level chronology of past periods | ||
| - **Topics Index** — keyword lookup table for O(1) "do I know about X?" judgment | ||
| **Before any lookup, check ROOT.md first:** | ||
| - Topic found in Topics Index → search memory (qmd or tree traversal) | ||
| - Topic NOT in Topics Index → use external search or answer from general knowledge | ||
| - This eliminates "loading to decide whether to load" — ROOT.md is always in context | ||
| **This is the core value of the compaction tree.** Search only works when you know what to search for. The Topics Index tells you what you know at a glance. | ||
| ## BM25 Query Construction | ||
| When using `qmd search` (BM25 mode), queries must be **keywords**, not natural language. | ||
| ### Rules | ||
| 1. Use **2-4 specific keywords** — more precise = better results | ||
| 2. **No natural language** — strip filler words | ||
| 3. **Try variations** — if first query misses, use synonyms or related terms | ||
| ### Examples | ||
| | Bad (natural language) | Good (keywords) | | ||
| |------------------------|-----------------| | ||
| | "How do I configure the database?" | "database config" | | ||
| | "What did we decide about caching?" | "caching decision" | | ||
| ## Tree Traversal | ||
| When qmd search returns insufficient results, traverse the compaction tree: | ||
| ``` | ||
| 1. ROOT.md Topics Index → confirm topic exists, note any file references | ||
| 2. ROOT.md Historical Summary → identify relevant time period | ||
| 3. memory/monthly/YYYY-MM.md → identify relevant week | ||
| 4. memory/weekly/YYYY-WNN.md → identify relevant day | ||
| 5. memory/daily/YYYY-MM-DD.md → detailed view | ||
| 6. memory/YYYY-MM-DD.md → full raw original | ||
| ``` | ||
| Always try qmd search first. Tree traversal is the fallback. | ||
| ## When to Search | ||
| - **Before any external lookup** — check ROOT.md, then search memory | ||
| - **Resuming prior work** — search for task context, past progress | ||
| - **Past decisions** — search daily logs and knowledge files | ||
| - **Credentials/configs** — search before asking user | ||
| ## Without qmd | ||
| If qmd is not installed (e.g., `--no-search` was used during init, or the user has a different RAG tool), the memory system still works: | ||
| - **ROOT.md** is always available — use the Topics Index for "do I know about this?" judgment | ||
| - **Tree traversal** works without qmd — just read the files directly: ROOT → monthly/ → weekly/ → daily/ → raw | ||
| - **Manual file reads** — use `ls memory/daily/` to find files, then read them | ||
| - Skip `qmd update` / `qmd search` commands — they will fail silently | ||
| The compaction tree and checkpoint protocol are fully independent of qmd. Search is a convenience layer, not a requirement. | ||
| ## After Modifying Files | ||
| If qmd is installed, re-index after changing memory or knowledge files: | ||
| ```bash | ||
| qmd update | ||
| ``` |
+14
-10
@@ -150,8 +150,10 @@ #!/usr/bin/env node | ||
| // Platform-specific core skill + shared skills | ||
| const coreSkillSrc = isOpenClaw ? "hipocampus-core-oc" : "hipocampus-core-cc"; | ||
| const sharedSkills = ["hipocampus-compaction", "hipocampus-search", "hipocampus-flush"]; | ||
| const allSkillSources = [coreSkillSrc, ...sharedSkills]; | ||
| // Installed as hipocampus-core (not hipocampus-core-cc/oc) | ||
| const allSkillDests = ["hipocampus-core", ...sharedSkills]; | ||
| // Plugin namespace is canonical (hipocampus:core); init copies transform to standalone (hipocampus-core). | ||
| // Invariant: frontmatter `name:` fields use hipocampus-xxx (not hipocampus:xxx), so replaceAll is safe. | ||
| const coreSkillSrc = isOpenClaw | ||
| ? { dir: join("platforms", "openclaw", "core"), name: "core" } | ||
| : { dir: join("skills", "core"), name: "core" }; | ||
| const sharedSkillNames = ["compaction", "search", "flush"]; | ||
| const allSkills = [coreSkillSrc, ...sharedSkillNames.map(s => ({ dir: join("skills", s), name: s }))]; | ||
| const allSkillDests = ["hipocampus-core", ...sharedSkillNames.map(s => `hipocampus-${s}`)]; | ||
@@ -161,12 +163,14 @@ // Claude Code: .claude/skills/ | OpenClaw: skills/ | ||
| for (let i = 0; i < allSkillSources.length; i++) { | ||
| const srcName = allSkillSources[i]; | ||
| for (let i = 0; i < allSkills.length; i++) { | ||
| const skill = allSkills[i]; | ||
| const destName = allSkillDests[i]; | ||
| const destDir = join(skillsBase, destName); | ||
| const destFile = join(destDir, "SKILL.md"); | ||
| const src = join(ROOT, "skills", srcName, "SKILL.md"); | ||
| const src = join(ROOT, skill.dir, "SKILL.md"); | ||
| if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true }); | ||
| // Always overwrite — ensures updates propagate on reinstall/upgrade | ||
| if (existsSync(src)) { | ||
| copyFileSync(src, destFile); | ||
| // Transform plugin namespace (hipocampus:xxx) to standalone (hipocampus-xxx) for init users | ||
| const content = readFileSync(src, "utf8").replaceAll("hipocampus:", "hipocampus-"); | ||
| writeFileSync(destFile, content); | ||
| console.log(` + skill: ${destName}`); | ||
@@ -173,0 +177,0 @@ } |
+4
-1
| { | ||
| "name": "hipocampus", | ||
| "version": "0.1.9", | ||
| "version": "0.2.1", | ||
| "description": "Drop-in memory harness for AI agents — 3-tier memory, compaction tree, hybrid search via qmd", | ||
@@ -39,6 +39,9 @@ "type": "module", | ||
| "files": [ | ||
| ".claude-plugin/", | ||
| "cli/", | ||
| "hooks/", | ||
| "spec/", | ||
| "templates/", | ||
| "skills/", | ||
| "platforms/", | ||
| "LICENSE", | ||
@@ -45,0 +48,0 @@ "README.md" |
| --- | ||
| name: hipocampus-compaction | ||
| description: "Build 5-level compaction tree (daily/weekly/monthly/root) with smart thresholds and fixed/tentative lifecycle. Run at session start when triggers are met, or via external scheduler." | ||
| --- | ||
| # Memory Compaction Tree | ||
| 5-level hierarchical index over raw memory logs. Compaction nodes are **search indices** — originals are never deleted. | ||
| ## Hierarchy | ||
| ``` | ||
| memory/ | ||
| ROOT.md <- root node (topic index, ~3K tokens, Layer 1) | ||
| 2026-03-15.md <- raw daily log (permanent, append-only) | ||
| daily/2026-03-15.md <- daily compaction node | ||
| weekly/2026-W11.md <- weekly compaction node | ||
| monthly/2026-03.md <- monthly compaction node | ||
| ``` | ||
| **Compaction chain:** Raw → Daily → Weekly → Monthly → Root | ||
| **Tree traversal (search):** Root → Monthly → Weekly → Daily → Raw | ||
| ## Fixed vs Tentative Nodes | ||
| Every compaction node has a status: | ||
| - **tentative** — period is still ongoing, regenerated when new data arrives | ||
| - **fixed** — period ended, never updated again | ||
| ```yaml | ||
| # Indicated in YAML frontmatter | ||
| --- | ||
| type: weekly | ||
| status: tentative | ||
| period: 2026-W11 | ||
| --- | ||
| ``` | ||
| **Key: tentative nodes are created immediately — ROOT.md is usable from day one.** | ||
| ## When to Run | ||
| Called from hipocampus-core Session Start step 7, or directly by an external scheduler (e.g., OpenClaw heartbeat). Check trigger conditions below. | ||
| ## Trigger Conditions | ||
| | Level | Tentative Create/Update | Fixed Transition | | ||
| |-------|------------------------|-----------------| | ||
| | Raw → Daily | On each new raw addition | Date changes | | ||
| | Daily → Weekly | On daily add/change | ISO week ended + 7 days elapsed | | ||
| | Weekly → Monthly | On weekly add/change | Month ended + 7 days elapsed | | ||
| | Monthly → Root | On monthly add/change | Never (root accumulates forever) | | ||
| ## Smart Thresholds | ||
| Below threshold: copy/concat verbatim (no information loss). | ||
| Above threshold: generate LLM keyword-dense summary. | ||
| | Level | Threshold | Above | Below | | ||
| |-------|-----------|-------|-------| | ||
| | Raw → Daily | ~200 lines | LLM keyword-dense summary | Copy raw verbatim | | ||
| | Daily → Weekly | ~300 lines combined | LLM keyword-dense summary | Concat dailies | | ||
| | Weekly → Monthly | ~500 lines combined | LLM keyword-dense summary | Concat weeklies | | ||
| | Monthly → Root | Always | Recursive recompaction | (N/A) | | ||
| ## Algorithm | ||
| **CRITICAL — STRICT CHAIN ORDER: Steps 2→3→4→5 MUST execute in sequence. NEVER skip a level.** | ||
| Each step feeds the next. Root reads from monthly. Monthly reads from weekly. Weekly reads from daily. If you skip a level, the chain breaks and data is lost or corrupted. | ||
| ``` | ||
| Raw → [Step 2] → Daily → [Step 3] → Weekly → [Step 4] → Monthly → [Step 5] → Root | ||
| ↑ ↑ ↑ ↑ | ||
| reads raw reads daily reads weekly reads monthly | ||
| writes daily/ writes weekly/ writes monthly/ writes ROOT.md | ||
| ``` | ||
| **NEVER:** | ||
| - Modify ROOT.md based on daily or weekly data (root reads ONLY from monthly) | ||
| - Modify monthly based on daily data (monthly reads ONLY from weekly) | ||
| - Skip Step 2 or 3 because "there's nothing new" — always verify by checking files | ||
| - Touch ROOT.md directly without going through the full chain | ||
| ### Step 1: Discover Candidates | ||
| Scan `memory/` for raw files. Group by date, ISO week, and month. Check each group against trigger conditions. | ||
| ### Step 2: Daily Compaction (max 1 per cycle) | ||
| **Input:** raw files (`memory/YYYY-MM-DD.md`) | ||
| **Output:** daily nodes (`memory/daily/YYYY-MM-DD.md`) | ||
| For each date where raw exists and daily needs create/update: | ||
| 1. Read raw file `memory/YYYY-MM-DD.md` | ||
| 2. Count lines — compare against ~200 line threshold | ||
| 3. Below threshold: copy raw verbatim to `memory/daily/YYYY-MM-DD.md` | ||
| 4. Above threshold: generate keyword-dense summary | ||
| 5. Write with frontmatter: | ||
| ```markdown | ||
| --- | ||
| type: daily | ||
| status: tentative | ||
| period: YYYY-MM-DD | ||
| source-files: [memory/YYYY-MM-DD.md] | ||
| topics: [keyword1, keyword2, keyword3] | ||
| --- | ||
| ## Topics | ||
| ## Key Decisions | ||
| ## Tasks Completed | ||
| ## Lessons Learned | ||
| ## Open Items | ||
| ``` | ||
| 6. If date has changed (raw is from a past date): set `status: fixed` | ||
| **CHECKPOINT:** Verify `memory/daily/` has the updated file before proceeding to Step 3. | ||
| ### Step 3: Weekly Compaction (max 1 per cycle) | ||
| **Input:** daily nodes (`memory/daily/YYYY-MM-DD.md`) — NEVER raw files | ||
| **Output:** weekly nodes (`memory/weekly/YYYY-WNN.md`) | ||
| **STOP-CHECK:** Did Step 2 produce or update a daily node? If not, skip Steps 3-5 entirely — there's nothing new to propagate. | ||
| For each ISO week where dailies exist and weekly needs create/update: | ||
| 1. Read all daily compaction files for that week (from `memory/daily/`, NOT from `memory/`) | ||
| 2. Count combined lines — compare against ~300 line threshold | ||
| 3. Below threshold: concat all dailies | ||
| 4. Above threshold: generate keyword-dense weekly summary | ||
| 5. Write to `memory/weekly/YYYY-WNN.md` with frontmatter | ||
| 6. If ISO week ended + 7 days elapsed: set `status: fixed` | ||
| **CHECKPOINT:** Verify `memory/weekly/` has the updated file before proceeding to Step 4. | ||
| ### Step 4: Monthly Compaction (max 1 per cycle) | ||
| **Input:** weekly nodes (`memory/weekly/YYYY-WNN.md`) — NEVER daily or raw files | ||
| **Output:** monthly nodes (`memory/monthly/YYYY-MM.md`) | ||
| **STOP-CHECK:** Did Step 3 produce or update a weekly node? If not, skip Steps 4-5 — there's nothing new to propagate. | ||
| For each month where weeklies exist and monthly needs create/update: | ||
| 1. Read all weekly compaction files for that month (from `memory/weekly/`, NOT from `memory/daily/`) | ||
| 2. Count combined lines — compare against ~500 line threshold | ||
| 3. Below threshold: concat all weeklies | ||
| 4. Above threshold: generate keyword-dense monthly summary | ||
| 5. Write to `memory/monthly/YYYY-MM.md` with frontmatter | ||
| 6. If month ended + 7 days elapsed: set `status: fixed` | ||
| **CHECKPOINT:** Verify `memory/monthly/` has the updated file before proceeding to Step 5. | ||
| ### Step 5: Root Compaction | ||
| **Input:** monthly nodes (`memory/monthly/YYYY-MM.md`) — NEVER weekly, daily, or raw files | ||
| **Output:** `memory/ROOT.md` | ||
| **STOP-CHECK:** Did Step 4 produce or update a monthly node? If not, DO NOT touch ROOT.md. | ||
| When a monthly node is created or updated: | ||
| 1. Read existing `memory/ROOT.md` (if exists) | ||
| 2. Read the new/updated monthly node (from `memory/monthly/`, NOT from any other directory) | ||
| 3. Recursive compaction: `root = recompact(existing_root + monthly_changes)` | ||
| - **Active Context**: replace with current week's highlights — what's in progress, immediate priorities | ||
| - **Recent Patterns**: update with newly emerged cross-cutting insights | ||
| - **Historical Summary**: append/compress older context — merge periods, keep brief summaries | ||
| - **Topics Index**: merge new topics, update existing entries with new sub-keywords and references | ||
| 4. Write to `memory/ROOT.md` | ||
| 5. If root exceeds size cap (`compaction.rootMaxTokens` in config, default 3000 tokens / ~100 lines): self-compress — compress Historical Summary first, keep Active Context and Topics Index intact | ||
| ```markdown | ||
| --- | ||
| type: root | ||
| status: tentative | ||
| last-updated: YYYY-MM-DD | ||
| --- | ||
| ## Active Context (recent ~7 days) | ||
| - topic: current state, what's happening now | ||
| ## Recent Patterns | ||
| - pattern: cross-cutting insight that emerged recently | ||
| ## Historical Summary | ||
| - YYYY-MM~MM: high-level summary of that period | ||
| - YYYY-MM: key events | ||
| ## Topics Index | ||
| - topic-keyword: sub-keywords, references → knowledge/file.md | ||
| - topic-keyword: sub-keywords | ||
| ``` | ||
| ### Step 6: OpenClaw ROOT.md Sync | ||
| **OpenClaw only:** Sync ROOT.md content into the "Compaction Root" section of MEMORY.md: | ||
| - Read MEMORY.md, find `## Compaction Root` section | ||
| - Replace everything between `## Compaction Root` and the next `##` heading (or EOF) with the Active Context, Recent Patterns, and Topics Index sections from ROOT.md | ||
| - This keeps the auto-loaded MEMORY.md in sync with the canonical ROOT.md | ||
| ### Step 7: Re-index | ||
| After writing any compaction files: | ||
| ```bash | ||
| qmd update | ||
| ``` | ||
| If vector search is enabled (`search.vector: true` in `hipocampus.config.json`): | ||
| ```bash | ||
| qmd embed | ||
| ``` | ||
| ## Guards | ||
| - **CHAIN ORDER IS MANDATORY:** Daily→Weekly→Monthly→Root. Never skip a level. Never read from a wrong source directory. | ||
| - **Each level reads ONLY from its immediate predecessor:** Root←Monthly←Weekly←Daily←Raw | ||
| - Raw files: **never delete** (permanent leaf nodes) | ||
| - Max 1 daily + 1 weekly + 1 monthly + 1 root per compaction cycle | ||
| - No empty summaries (minimum 50 bytes) | ||
| - Skip failed file reads — never abort entire compaction | ||
| - qmd update failure: warning only, not fatal | ||
| - Root self-compresses when exceeding size cap (shrink older topics first) | ||
| - Keyword-dense format only — no prose, no narrative. Optimized for BM25 recall. | ||
| - **If you feel tempted to "just update ROOT.md quickly" — STOP. Run the full chain.** | ||
| ## Edge Cases | ||
| - **Empty days:** No daily compaction node is generated for days without raw logs. Weekly naturally skips those days. | ||
| - **First day:** Create the full tentative tree immediately (daily → weekly → monthly → root). ROOT.md is usable from day one. | ||
| - **Lifecycle example:** | ||
| - Day 1: raw created → daily(tentative) → weekly(tentative) → monthly(tentative) → ROOT | ||
| - Day 2: daily(tentative) updated, weekly(tentative) updated, monthly(tentative) updated, ROOT updated | ||
| - Week ends + 7 days: weekly → fixed, new weekly(tentative) starts | ||
| - Month ends + 7 days: monthly → fixed, new monthly(tentative) starts |
| --- | ||
| name: hipocampus-core | ||
| description: "3-tier agent memory system with 5-level compaction tree. Claude Code version. Defines session start protocol, end-of-task checkpoints, and memory file management. MUST be followed every session." | ||
| --- | ||
| # Hipocampus — Agent Memory Protocol (Claude Code) | ||
| ## Memory Architecture | ||
| ``` | ||
| Layer 1 (System Prompt — auto-loaded via @import): | ||
| SCRATCHPAD.md ~150 lines active working state | ||
| WORKING.md ~100 lines current tasks | ||
| TASK-QUEUE.md ~50 lines task backlog | ||
| memory/ROOT.md ~100 lines topic index of all memory (~3K tokens) | ||
| Long-term memory and user profile are managed by Claude Code's platform auto memory. | ||
| Layer 2 (On-Demand — read when needed): | ||
| memory/YYYY-MM-DD.md raw daily logs (permanent, never deleted) | ||
| knowledge/*.md detailed knowledge (searchable via qmd) | ||
| plans/*.md task plans | ||
| Layer 3 (Search — via qmd + compaction tree): | ||
| memory/daily/YYYY-MM-DD.md daily compaction nodes | ||
| memory/weekly/YYYY-WNN.md weekly compaction nodes | ||
| memory/monthly/YYYY-MM.md monthly compaction nodes | ||
| Tree traversal: ROOT → monthly → weekly → daily → raw | ||
| ``` | ||
| ## Session Start (MANDATORY — run on first user message) | ||
| **FIRST RESPONSE RULE:** On the very first user message of every session, before doing ANYTHING else: | ||
| Run the Session Start protocol below FIRST. This takes priority over ANY user request — even if the user asks you to do something specific. Complete the step below, ONLY THEN respond to the user. | ||
| SCRATCHPAD.md, WORKING.md, TASK-QUEUE.md, memory/ROOT.md are auto-loaded via @import in CLAUDE.md. No manual read needed. | ||
| **This procedure must be completed before responding to the user NO MATTER WHAT** | ||
| 1. **DO NOT SKIP** **DO NOT COMPROMISE** **Compaction maintenance (cooldown-gated):** | ||
| Read `memory/.compaction-state.json` and `hipocampus.config.json` (`compaction.cooldownHours`, default 3). | ||
| - **Within cooldown:** Skip compaction subagent — no dispatch needed. | ||
| - **Cooldown expired, file missing, or `cooldownHours` is 0:** Write `memory/.compaction-state.json` with `{ "lastCompactionRun": "<current ISO timestamp>" }`, then dispatch a subagent to run hipocampus-compaction skill (chain: Daily→Weekly→Monthly→Root), then run `hipocampus compact` + `qmd update` + `qmd embed`. | ||
| State file is written immediately on dispatch (fire-and-forget), not after subagent completion. The cooldown tracks "a compaction was initiated," not "a compaction succeeded." | ||
| **This step is MANDATORY every session. You MUST read the state file and make the judgment. The only thing that may be skipped is the subagent dispatch when cooldown is active.** | ||
| **This procedure must be completed before responding to the user NO MATTER WHAT** | ||
| ## End-of-Task Checkpoint (MANDATORY) | ||
| After completing any task, **dispatch a subagent** to append a structured log to `memory/YYYY-MM-DD.md`. | ||
| Compose the subagent task: | ||
| > Append the following to memory/YYYY-MM-DD.md: | ||
| > | ||
| > ## [Topic Name] | ||
| > - request: [what the user asked] | ||
| > - analysis: [what you researched/analyzed] | ||
| > - decisions: [choices made with rationale] | ||
| > - outcome: [what was done, files changed] | ||
| > - references: [knowledge/ files, external sources] | ||
| **The subagent only needs to do one thing: append to the daily log.** This is the source of truth — everything else (SCRATCHPAD, WORKING, TASK-QUEUE) is updated lazily at next session start or by the agent naturally during work. | ||
| **The subagent needs the task summary you provide** — it doesn't have access to the conversation. | ||
| **Priority if timeout imminent** (no time for subagent — write directly to `memory/YYYY-MM-DD.md`) | ||
| ## Proactive Session Dump | ||
| **Do not wait for task completion to write to the daily log.** Proactively dispatch a subagent to append to `memory/YYYY-MM-DD.md` when: | ||
| - The conversation has been going for ~20+ messages without a checkpoint | ||
| - You sense the context is getting large | ||
| - A significant decision or analysis was just completed, even if the overall task isn't done | ||
| - You're switching between topics within the same task | ||
| Compose the subagent task with a summary of what to dump, same as the checkpoint format. The subagent writes the file; the main session stays clean. | ||
| This protects against context compression — if the platform compresses your conversation history, undumped details are lost forever. Write early, write often. The daily log is append-only, so multiple dumps in the same session are fine. | ||
| ## File Size Targets | ||
| | File | Target | When Exceeded | | ||
| |------|--------|---------------| | ||
| | ROOT.md | ~100 lines (~3K tokens) | Automatic recursive self-compression | | ||
| | SCRATCHPAD | ~150 lines | Remove completed items | | ||
| | WORKING | ~100 lines | Remove completed tasks | | ||
| | TASK-QUEUE | ~50 lines | Archive completed items | | ||
| ## Rules | ||
| - Long-term facts are managed by platform auto memory. No separate MEMORY.md file. | ||
| - Raw daily logs (`memory/YYYY-MM-DD.md`): **permanent**. Never delete or edit after session. | ||
| - ROOT.md: managed by compaction process. Do not manually edit. | ||
| - All memory writes via subagent — never pollute main session with memory operations. | ||
| - If this session ends NOW, the next session must be able to continue immediately. | ||
| - Don't skip checkpoints — lost context means you forget. | ||
| ## Edge Cases | ||
| - **Midnight-spanning session:** Use the session start date for the raw log file name. Do not split across dates. | ||
| - **Returning after long absence:** "Most recent daily" means the latest file that exists, whether it's from yesterday or last week. |
| --- | ||
| name: hipocampus-core | ||
| description: "3-tier agent memory system with 5-level compaction tree. OpenClaw version. Defines session start protocol, end-of-task checkpoints, and memory file management. MUST be followed every session." | ||
| --- | ||
| # Hipocampus — Agent Memory Protocol (OpenClaw) | ||
| ## Memory Architecture | ||
| ``` | ||
| Layer 1 (System Prompt — read at session start): | ||
| MEMORY.md ~50 lines long-term memory (Core=frozen, Adaptive=compactable) | ||
| USER.md ~50 lines user profile and preferences | ||
| SCRATCHPAD.md ~150 lines active working state | ||
| WORKING.md ~100 lines current tasks | ||
| TASK-QUEUE.md ~50 lines task backlog | ||
| memory/ROOT.md ~100 lines topic index of all memory (~3K tokens, via Compaction Root in MEMORY.md) | ||
| Layer 2 (On-Demand — read when needed): | ||
| memory/YYYY-MM-DD.md raw daily logs (permanent, never deleted) | ||
| knowledge/*.md detailed knowledge (searchable via qmd) | ||
| plans/*.md task plans | ||
| Layer 3 (Search — via qmd + compaction tree): | ||
| memory/daily/YYYY-MM-DD.md daily compaction nodes | ||
| memory/weekly/YYYY-WNN.md weekly compaction nodes | ||
| memory/monthly/YYYY-MM.md monthly compaction nodes | ||
| Tree traversal: ROOT → monthly → weekly → daily → raw | ||
| ``` | ||
| ## Session Start (MANDATORY — run on first user message) | ||
| **FIRST RESPONSE RULE:** On the very first user message of every session, before doing ANYTHING else: | ||
| Run the Session Start protocol below FIRST (ALL steps. NO SKIP.) This takes priority over ANY user request — even if the user asks you to do something specific. Complete ALL steps below, ONLY THEN respond to the user. | ||
| MEMORY.md, USER.md, memory/ROOT.md (via Compaction Root section) are auto-loaded by the platform. | ||
| **ALL 4 procedures must be completed before responding to the user NO MATTER WHAT** | ||
| 1. **DO NOT SKIP** Read `SCRATCHPAD.md` — current work state | ||
| 2. **DO NOT SKIP** Read `WORKING.md` — active tasks | ||
| 3. **DO NOT SKIP** Read `TASK-QUEUE.md` — pending items | ||
| 4. **DO NOT SKIP** **DO NOT COMPROMISE** **Compaction maintenance (cooldown-gated):** | ||
| Read `memory/.compaction-state.json` and `hipocampus.config.json` (`compaction.cooldownHours`, default 3). | ||
| - **Within cooldown:** Skip compaction subagent — no dispatch needed. | ||
| - **Cooldown expired, file missing, or `cooldownHours` is 0:** Write `memory/.compaction-state.json` with `{ "lastCompactionRun": "<current ISO timestamp>" }`, then dispatch a subagent to run hipocampus-compaction skill USING SUBAGENTS (chain: Daily→Weekly→Monthly→Root), then run `hipocampus compact` + `qmd update` + `qmd embed`. | ||
| State file is written immediately on dispatch (fire-and-forget), not after subagent completion. The cooldown tracks "a compaction was initiated," not "a compaction succeeded." | ||
| **This step is MANDATORY every session. You MUST read the state file and make the judgment. The only thing that may be skipped is the subagent dispatch when cooldown is active.** | ||
| **ALL 4 procedures must be completed before responding to the user NO MATTER WHAT** | ||
| Note: HEARTBEAT.md also handles needs-summarization at every heartbeat (~30 min). | ||
| ## End-of-Task Checkpoint (MANDATORY) | ||
| After completing any task, **dispatch a subagent** to append a structured log to `memory/YYYY-MM-DD.md`. | ||
| Compose the subagent task: | ||
| > Append the following to memory/YYYY-MM-DD.md: | ||
| > | ||
| > ## [Topic Name] | ||
| > - request: [what the user asked] | ||
| > - analysis: [what you researched/analyzed] | ||
| > - decisions: [choices made with rationale] | ||
| > - outcome: [what was done, files changed] | ||
| > - references: [knowledge/ files, external sources] | ||
| **The subagent only needs to do one thing: append to the daily log.** This is the source of truth — everything else (SCRATCHPAD, WORKING, TASK-QUEUE, MEMORY.md) is updated lazily at next session start or by the agent naturally during work. | ||
| **The subagent needs the task summary you provide** — it doesn't have access to the conversation. | ||
| **Priority if timeout imminent** (no time for subagent — write directly to `memory/YYYY-MM-DD.md`) | ||
| ## Proactive Session Dump | ||
| **Do not wait for task completion to write to the daily log.** Proactively dispatch a subagent to append to `memory/YYYY-MM-DD.md` when: | ||
| - The conversation has been going for ~20+ messages without a checkpoint | ||
| - You sense the context is getting large | ||
| - A significant decision or analysis was just completed, even if the overall task isn't done | ||
| - You're switching between topics within the same task | ||
| Compose the subagent task with a summary of what to dump, same as the checkpoint format. The subagent writes the file; the main session stays clean. | ||
| This protects against context compression — if the platform compresses your conversation history, undumped details are lost forever. Write early, write often. The daily log is append-only, so multiple dumps in the same session are fine. | ||
| ## File Size Targets | ||
| | File | Target | When Exceeded | | ||
| |------|--------|---------------| | ||
| | MEMORY.md Core | ~50 lines | Never touch — frozen | | ||
| | MEMORY.md Adaptive | ~50 lines | Prune oldest entries | | ||
| | ROOT.md | ~100 lines (~3K tokens) | Automatic recursive self-compression | | ||
| | SCRATCHPAD | ~150 lines | Remove completed items | | ||
| | WORKING | ~100 lines | Remove completed tasks | | ||
| | TASK-QUEUE | ~50 lines | Archive completed items | | ||
| ## Rules | ||
| - MEMORY.md Core section: **FROZEN**. Never compact, modify, or remove. | ||
| - MEMORY.md Adaptive section: append-only within session, compactable across sessions. | ||
| - Raw daily logs (`memory/YYYY-MM-DD.md`): **permanent**. Never delete or edit after session. | ||
| - ROOT.md: managed by compaction process. Do not manually edit. | ||
| - All memory writes via subagent — never pollute main session with memory operations. | ||
| - If this session ends NOW, the next session must be able to continue immediately. | ||
| - Don't skip checkpoints — lost context means you forget. | ||
| ## Edge Cases | ||
| - **Midnight-spanning session:** Use the session start date for the raw log file name. Do not split across dates. | ||
| - **Returning after long absence:** "Most recent daily" means the latest file that exists, whether it's from yesterday or last week. |
| --- | ||
| name: hipocampus-flush | ||
| description: "Manual memory flush: dump current session context to daily raw log via subagent. Invoke with /hipocampus-flush. Run hipocampus-compaction afterwards for tree propagation and qmd reindex." | ||
| user_invocable: true | ||
| --- | ||
| # Hipocampus Memory Flush | ||
| Dump current session context to the daily raw log. Use when you want to persist what happened in this session without waiting for End-of-Task Checkpoint or context compression. | ||
| For full compaction (needs-summarization processing, tree propagation, qmd reindex), run hipocampus-compaction skill after this. | ||
| ## Steps | ||
| ### 1. Compose session summary | ||
| Gather a summary of everything discussed in this session so far. For each topic: | ||
| ```markdown | ||
| ## [Topic Name] | ||
| - request: what the user asked | ||
| - analysis: what you researched/analyzed | ||
| - decisions: choices made with rationale | ||
| - outcome: what was done, files changed | ||
| - references: knowledge/ files, external sources | ||
| ``` | ||
| ### 2. Dispatch subagent | ||
| **Dispatch a subagent** with the session summary and this task: | ||
| > Hipocampus memory flush. Append the following structured log to memory/YYYY-MM-DD.md (today's date). Then run `hipocampus compact` to propagate through the tree. | ||
| > | ||
| > [paste session summary here] | ||
| The subagent writes the files and runs compact. The main session stays clean. | ||
| ### 3. Report | ||
| Confirm the flush completed: | ||
| - Topics flushed | ||
| - Subagent status |
| --- | ||
| name: hipocampus-search | ||
| description: "Search memory using qmd (BM25 + optional vector) and compaction tree traversal. Use ROOT.md to decide whether to search memory or look externally. Always check memory before external lookups." | ||
| --- | ||
| # Hipocampus Search | ||
| ## Quick Reference | ||
| | Action | Command | | ||
| |--------|---------| | ||
| | Hybrid search (best quality) | `qmd query "keyword1 keyword2"` | | ||
| | Keyword search (fast) | `qmd search "keyword1 keyword2"` | | ||
| | Vector search only | `qmd vsearch "semantic query"` | | ||
| | Find files | `qmd search "query" --files` | | ||
| | Read file | `qmd get "path/to/file.md"` | | ||
| | Re-index | `qmd update` | | ||
| ## Which Search to Use | ||
| Check `hipocampus.config.json`: | ||
| - `search.vector: true` (default) → `qmd query` for best results (BM25 + vector + rerank) | ||
| - `search.vector: false` → `qmd search` for BM25 keyword search | ||
| ## ROOT.md — "Do I Know About This?" | ||
| `memory/ROOT.md` is a functional index of everything in memory, auto-loaded every session. It has four sections: | ||
| - **Active Context** — current week's work and priorities (immediate situational awareness) | ||
| - **Recent Patterns** — cross-cutting insights not tied to a specific time period | ||
| - **Historical Summary** — high-level chronology of past periods | ||
| - **Topics Index** — keyword lookup table for O(1) "do I know about X?" judgment | ||
| **Before any lookup, check ROOT.md first:** | ||
| - Topic found in Topics Index → search memory (qmd or tree traversal) | ||
| - Topic NOT in Topics Index → use external search or answer from general knowledge | ||
| - This eliminates "loading to decide whether to load" — ROOT.md is always in context | ||
| **This is the core value of the compaction tree.** Search only works when you know what to search for. The Topics Index tells you what you know at a glance. | ||
| ## BM25 Query Construction | ||
| When using `qmd search` (BM25 mode), queries must be **keywords**, not natural language. | ||
| ### Rules | ||
| 1. Use **2-4 specific keywords** — more precise = better results | ||
| 2. **No natural language** — strip filler words | ||
| 3. **Try variations** — if first query misses, use synonyms or related terms | ||
| ### Examples | ||
| | Bad (natural language) | Good (keywords) | | ||
| |------------------------|-----------------| | ||
| | "How do I configure the database?" | "database config" | | ||
| | "What did we decide about caching?" | "caching decision" | | ||
| ## Tree Traversal | ||
| When qmd search returns insufficient results, traverse the compaction tree: | ||
| ``` | ||
| 1. ROOT.md Topics Index → confirm topic exists, note any file references | ||
| 2. ROOT.md Historical Summary → identify relevant time period | ||
| 3. memory/monthly/YYYY-MM.md → identify relevant week | ||
| 4. memory/weekly/YYYY-WNN.md → identify relevant day | ||
| 5. memory/daily/YYYY-MM-DD.md → detailed view | ||
| 6. memory/YYYY-MM-DD.md → full raw original | ||
| ``` | ||
| Always try qmd search first. Tree traversal is the fallback. | ||
| ## When to Search | ||
| - **Before any external lookup** — check ROOT.md, then search memory | ||
| - **Resuming prior work** — search for task context, past progress | ||
| - **Past decisions** — search daily logs and knowledge files | ||
| - **Credentials/configs** — search before asking user | ||
| ## Without qmd | ||
| If qmd is not installed (e.g., `--no-search` was used during init, or the user has a different RAG tool), the memory system still works: | ||
| - **ROOT.md** is always available — use the Topics Index for "do I know about this?" judgment | ||
| - **Tree traversal** works without qmd — just read the files directly: ROOT → monthly/ → weekly/ → daily/ → raw | ||
| - **Manual file reads** — use `ls memory/daily/` to find files, then read them | ||
| - Skip `qmd update` / `qmd search` commands — they will fail silently | ||
| The compaction tree and checkpoint protocol are fully independent of qmd. Search is a convenience layer, not a requirement. | ||
| ## After Modifying Files | ||
| If qmd is installed, re-index after changing memory or knowledge files: | ||
| ```bash | ||
| qmd update | ||
| ``` |
No alert changes
Improved metrics
- Total package byte prevSize
124360
0.99%- Number of package files
22
10%- Lines of code
751
3.3%No dependency changes