kevin-hs-sohn/hipocampus

# Hipocampus — Agent Memory Protocol (Codex CLI)

## Memory Architecture

```
Layer 1 (System Prompt — read at session start):
  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 Codex's built-in memory system.

Layer 2 (On-Demand — read when needed):

# 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):

# Hipocampus — Agent Memory Protocol (OpenCode)

## 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 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
```

# 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):

# 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

# Memory Recall Protocol

Use this when the user's question may relate to past memory. Three-step fallback: ROOT.md O(1) lookup → manifest LLM selection → qmd search.

## Step 1: ROOT.md Triage (O(1) — always try first)

Check ROOT.md Topics Index for the query topic.

- **Direct match found** → read the referenced file (knowledge/, daily log date, etc.). Done.
- **Partial match / related topic found** → read referenced file, check if it answers the query. Done if yes.
- **No match at all** → proceed to Step 2.

**Decision rule:** If Topics Index contains a keyword within 1 semantic hop of the query, it's a match. "배포" matches "deployment". "CI/CD" matches "github-actions".

# 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