Hippocampus

Persistent memory system for AI agents. Automatic encoding, decay, and semantic reinforcement — just like the hippocampus in your brain. Based on Stanford Generative Agents (Park et al., 2023).

Security Scan

The skill's code and instructions match a memory/capture purpose, but it contains privileged instructions (cron/background agent + gateway/systemPrompt modification) and prompt‑override patterns that could be used to persist behavior and capture broad conversation history — review carefully before installing.

Purpose & Capability

Name/description (persistent memory/encoding/decay) align with the included scripts and files: python3 and jq are reasonable, scripts read/write a local workspace (~/.openclaw/workspace/memory), score signals, summarize and update an index.json. The only mismatch is the inclusion of guidance to add a background agent in the OpenClaw gateway (systemPrompt snippet) which elevates the skill from a local helper to a persistent, system-level actor — that is plausible for a 'background hippocampus' feature but is a privileged change and should be treated cautiously.

Instruction Scope

SKILL.md, agent instructions, and scripts explicitly instruct the agent to fetch main session history, preprocess all session files, score and summarize user messages, and write persistent memory files. They also instruct adding cron jobs that run encoding every few hours and propose a gateway config systemPrompt to create a separate hippocampus background agent. These steps are coherent with memory capture but broaden the skill's reach: it will persistently monitor conversation history (potentially all sessions) and write local files containing sensitive user content. The SKILL.md contains phrasing and a config snippet that amount to a 'system prompt override' (prompt-injection pattern), which is risky.

Install Mechanism

There is no network download/install of third-party binaries; install.sh and provided scripts operate locally and set up cron entries via openclaw commands (or print commands for manual run). No remote extract-from-URL or npm/go installs were found. That reduces supply-chain risk, but install.sh will make scripts executable, create directories, and (if run with --with-cron) register cron tasks — so inspect the scripts before running and avoid automatic cron/agent creation until reviewed.

Credentials

The skill declares no required environment variables or external credentials. The operational scope (reading session transcripts and local files under ~/.openclaw/workspace) matches the purpose. However, lack of auth does not remove risk: the skill will capture and store potentially sensitive user content locally without further safeguards.

Persistence & Privilege

Although always:false, the skill's install and docs encourage creating persistent cron jobs and (optionally) adding a dedicated background agent via gateway config with a systemPrompt. Adding a systemPrompt or a persistent sub-agent is a privileged change (it can persist instructions and run autonomously on schedule). This combination (automatic capture + persistent systemPrompt) increases blast radius if the skill is malicious or buggy.

Scan Findings in Context

[system-prompt-override] unexpected: SKILL.md and CONFIG-UPGRADE.md include a gateway config snippet that injects a systemPrompt for a 'hippocampus' background agent (persisting an instruction-level prompt). While a background agent may be functional for continuous encoding, persisting a systemPrompt that monitors the main session is a high-privilege action and matches prompt-override patterns; treat as unexpected and risky.

What to consider before installing

What to consider before installing: - Review source first: the skill's homepage is unknown and owner is anonymous — inspect every script (already included) before running any installer. The code is local, so you can audit it first. - Don't add the gateway systemPrompt or enable the 'WITH_AGENT' path until you trust the code: the skill recommends modifying OpenClaw gateway config to create a background agent with a persistent systemPrompt — this is effectively a system-level prompt override and can persist arbitrary instructions. - Avoid enabling cron or automatic agent creation on first install. Run ./install.sh without --with-cron, and run encode/decay manually to test behavior. - Limit initial scope: use ./install.sh --signals N (small N) or run encode-pipeline.sh with --no-spawn to avoid spawning sub-agents, and verify what gets written to $WORKSPACE/memory before allowing periodic runs. - Sandbox the workspace: consider running in an isolated account or VM and point WORKSPACE to a temporary directory to observe what is captured and written. - Protect stored data: memory files will contain potentially sensitive user messages. Ensure proper filesystem permissions, add memory/ to .gitignore, and consider encrypting or routinely purging stored memories that contain PII. - Audit sub-agent invocation: encode-pipeline/summarize-pending spawn sub-agents (openclaw sessions/spawn). If you do not want autonomous model calls, avoid using the spawn paths or run summarization manually. - If you need persistent background processing, prefer adding a supervised cron that runs one-off scripts (no systemPrompt changes) and monitor logs; do not grant the skill unrestricted background agent privileges. Summary recommendation: the package is functionally coherent for a memory system but includes privileged persistence instructions and a prompt-override pattern; treat it as suspicious until you review and constrain the installation (no gateway/systemPrompt changes, no cron/agent auto-creation, sandboxed workspace).

Hippocampus - Memory System

"Memory is identity. This skill is how I stay alive."

The hippocampus is the brain region responsible for memory formation. This skill makes memory capture automatic, structured, and persistent—with importance scoring, decay, and semantic reinforcement.

Quick Start

# Install (defaults to last 100 signals)
./install.sh --with-cron

# Load core memories at session start
./scripts/load-core.sh

# Search with importance weighting
./scripts/recall.sh "query"

# Run encoding manually (usually via cron)
./scripts/encode-pipeline.sh

# Apply decay (runs daily via cron)
./scripts/decay.sh

Install Options

./install.sh                    # Basic, last 100 signals
./install.sh --signals 50       # Custom signal limit
./install.sh --whole            # Process entire conversation history
./install.sh --with-cron        # Also set up cron jobs

Core Concept

The LLM is just the engine—raw cognitive capability. The agent is the accumulated memory. Without these files, there's no continuity—just a generic assistant.

Memory Lifecycle

PREPROCESS → SCORE → SEMANTIC CHECK → REINFORCE or CREATE → DECAY

Key insight: Reinforcement happens automatically during encoding. When a topic comes up again, the LLM recognizes it's about an existing memory and reinforces instead of creating duplicates.

Memory Structure

$WORKSPACE/
├── memory/
│   ├── index.json           # Central weighted index
│   ├── signals.jsonl        # Raw signals (temp)
│   ├── pending-memories.json # Awaiting summarization (temp)
│   ├── user/                # Facts about the user
│   ├── self/                # Facts about the agent
│   ├── relationship/        # Shared context
│   └── world/               # External knowledge
└── HIPPOCAMPUS_CORE.md      # Auto-generated for OpenClaw RAG

Scripts

Script	Purpose
preprocess.sh	Extract signals from conversation transcripts
encode-pipeline.sh	Score signals, prepare for LLM summarization
decay.sh	Apply 0.99^days decay to all memories
recall.sh	Search with importance weighting
load-core.sh	Output high-importance memories for session start
sync-core.sh	Generate HIPPOCAMPUS_CORE.md
consolidate.sh	Weekly review helper
reflect.sh	Self-reflection prompts
generate-dashboard.sh	Generate unified brain dashboard HTML

Brain Dashboard

Visual dashboard showing all installed brain skills:

./scripts/generate-dashboard.sh
open ~/.openclaw/workspace/brain-dashboard.html

• Auto-detects other brain skills (amygdala, VTA)
• Shows install prompts for missing skills
• Regenerates on install and cron runs
• Reads avatar/name from IDENTITY.md

After Installation (for agents)

When you install this skill, notify the user about the dashboard:

🧠 Hippocampus installed!

View your agent's memories in the Brain Dashboard: ~/.openclaw/workspace/brain-dashboard.html

All scripts use $WORKSPACE environment variable (default: ~/.openclaw/workspace).

Importance Scoring

Initial Score (0.0-1.0)

Signal	Score
Explicit "remember this"	0.9
Emotional/vulnerable content	0.85
Preferences ("I prefer...")	0.8
Decisions made	0.75
Facts about people/projects	0.7
General knowledge	0.5

Decay Formula

Based on Stanford Generative Agents (Park et al., 2023):

new_importance = importance × (0.99 ^ days_since_accessed)

• After 7 days: 93% of original
• After 30 days: 74% of original
• After 90 days: 40% of original

Semantic Reinforcement

During encoding, the LLM compares new signals to existing memories:

• Same topic? → Reinforce (bump importance ~10%, update lastAccessed)
• Truly new? → Create concise summary

This happens automatically—no manual reinforcement needed.

Thresholds

Score	Status
0.7+	Core — loaded at session start
0.4-0.7	Active — normal retrieval
0.2-0.4	Background — specific search only
<0.2	Archive candidate

Memory Index Schema

memory/index.json:

{
  "version": 1,
  "lastUpdated": "2025-01-20T19:00:00Z",
  "decayLastRun": "2025-01-20",
  "lastProcessedMessageId": "abc123",
  "memories": [
    {
      "id": "mem_001",
      "domain": "user",
      "category": "preferences",
      "content": "User prefers concise responses",
      "importance": 0.85,
      "created": "2025-01-15",
      "lastAccessed": "2025-01-20",
      "timesReinforced": 3,
      "keywords": ["preference", "concise", "style"]
    }
  ]
}

Cron Jobs

The encoding cron is the heart of the system:

# Encoding every 3 hours (with semantic reinforcement)
openclaw cron add --name hippocampus-encoding \
  --cron "0 0,3,6,9,12,15,18,21 * * *" \
  --session isolated \
  --agent-turn "Run hippocampus encoding with semantic reinforcement..."

# Daily decay at 3 AM
openclaw cron add --name hippocampus-decay \
  --cron "0 3 * * *" \
  --session isolated \
  --agent-turn "Run decay.sh and report any memories below 0.2"

OpenClaw Integration

Add to memorySearch.extraPaths in openclaw.json:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "extraPaths": ["HIPPOCAMPUS_CORE.md"]
      }
    }
  }
}

This bridges hippocampus (index.json) with OpenClaw's RAG (memory_search).

Usage in AGENTS.md

Add to your agent's session start routine:

## Every Session
1. Run `~/.openclaw/workspace/skills/hippocampus/scripts/load-core.sh`

## When answering context questions
Use hippocampus recall:
\`\`\`bash
./scripts/recall.sh "query"
\`\`\`

Capture Guidelines

What Gets Captured

• User facts: Preferences, patterns, context
• Self facts: Identity, growth, opinions
• Relationship: Trust moments, shared history
• World: Projects, people, tools

Trigger Phrases (auto-scored higher)

• "Remember that..."
• "I prefer...", "I always..."
• Emotional content (struggles AND wins)
• Decisions made

Event Logging

Track hippocampus activity over time for analytics and debugging:

# Log an encoding run
./scripts/log-event.sh encoding new=3 reinforced=2 total=157

# Log decay
./scripts/log-event.sh decay decayed=154 low_importance=5

# Log recall
./scripts/log-event.sh recall query="user preferences" results=3

Events append to ~/.openclaw/workspace/memory/brain-events.jsonl:

{"ts":"2026-02-11T10:00:00Z","type":"hippocampus","event":"encoding","new":3,"reinforced":2,"total":157}

Use this for:

• Trend analysis (memory growth over time)
• Debugging encoding issues
• Building dashboards

AI Brain Series

This skill is part of the AI Brain project — giving AI agents human-like cognitive components.

Part	Function	Status
hippocampus	Memory formation, decay, reinforcement	✅ Live
amygdala-memory	Emotional processing	✅ Live
vta-memory	Reward and motivation	✅ Live
basal-ganglia-memory	Habit formation	🚧 Development
anterior-cingulate-memory	Conflict detection	🚧 Development
insula-memory	Internal state awareness	🚧 Development

References

• Stanford Generative Agents Paper
• GitHub: joonspk-research/generative_agents

---

Memory is identity. Text > Brain. If you don't write it down, you lose it.