Hipocampus Core

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

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 and memory/ROOT.md — pending items and topic index

4. DO NOT SKIP DO NOT COMPROMISE Compaction maintenance (cooldown-gated): Read memory/.compaction-state.json and hipocampus.config.json (compaction.cooldownHours, default 3).

   Compaction triggers (any ONE is sufficient):

   • Cooldown expired: cooldownHours since lastCompactionRun
   • Raw volume: rawLinesSinceLastCompaction > 300
   • Checkpoint count: checkpointsSinceLastCompaction > 5
   • State file missing or cooldownHours is 0

   If no trigger is met: skip compaction subagent. If any trigger is met: write memory/.compaction-state.json with { "lastCompactionRun": "<current ISO timestamp>", "rawLinesSinceLastCompaction": 0, "checkpointsSinceLastCompaction": 0 }, then dispatch compaction subagent.

   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 no trigger is met. ALL 4 procedures must be completed before responding to the user NO MATTER WHAT

Note: hipocampus hooks in .codex/hooks.json handle event-driven mechanical compaction — no manual scheduling needed.

Memory Recall

When the user's question may relate to past memory, use the hipocampus-recall skill for structured retrieval. See hipocampus/skills/recall/SKILL.md.

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] [type]

• 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]

Where type is: project | feedback | user | reference

For feedback entries, use:

[Feedback Topic] [feedback]

• rule: [the behavioral rule]
• why: [reason given]
• how-to-apply: [when/where this applies]

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.

After appending to the daily log, the subagent should also increment the checkpoint counter in memory/.compaction-state.json: read the file, increment checkpointsSinceLastCompaction by 1, write back. If the file or field is missing, start from 0.

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)