Tools
Hippocampus
By Three-layer working memory plugin for OpenClaw agents — daily notes, rolling synthesis, permanent knowledge graduation
Install
npm install
#Configuration Example
{
"plugins": {
"entries": {
"hippocampus": {}
}
}
}README
# Hippocampus
Working memory for [OpenClaw](https://github.com/openclaw/openclaw) agents.
When a conversation grows beyond a session, OpenClaw agents forget. Hippocampus gives them a rolling context synthesis that bridges daily notes and permanent memory — so agents wake up knowing what's happening, what's blocked, and what's owed.
## What it does
Three memory layers, working together:
1. **Daily notes** (`memory/YYYY-MM-DD.md`) — raw session logs your agents already write
2. **HIPPOCAMPUS.md** — a rolling synthesis (default: 14 days), auto-generated daily by cron. Loaded into every session automatically.
3. **MEMORY.md** — permanent curated knowledge, graduated from hippocampus when patterns prove durable
The synthesis is the key innovation. It doesn't just store — it *synthesizes*. Your agent's HIPPOCAMPUS.md reads like a briefing: what's top of mind, what threads are open, what commitments are outstanding, what happened recently.
## Quick start
```bash
openclaw plugins install hippocampus
```
That's it for a single agent. The plugin activates immediately:
- HIPPOCAMPUS.md is injected into every session via `prependSystemContext`
- The `hippocampus-sync` companion skill is available for cron
- The `hippocampus_setup` and `hippocampus_graduate` tools are registered
### Set up the daily synthesis
Create a cron job that runs the synthesis skill daily:
```bash
openclaw cron add \
--agent main \
--schedule "0 4 * * *" \
--name "hippocampus-sync" \
--prompt "Run the hippocampus-sync skill"
```
Or ask your agent: *"Set up hippocampus for me"* — the agent will use the `hippocampus_setup` tool to walk you through it conversationally.
### Interactive setup (recommended)
The setup wizard scans your instance and shows you exactly what hippocampus will do:
```bash
openclaw hippocampus setup
```
Or tell your agent: *"Run hippocampus setup"* — works via Telegram, Slack, or any channel.
## How it works
### Session start
The `before_prompt_build` hook reads HIPPOCAMPUS.md from the agent's workspace and injects it as `prependSystemContext`. The agent wakes up with full rolling context — no tool call needed, it's just there.
### Daily synthesis (cron)
The `hippocampus-sync` skill runs daily via cron. It reads the agent's memory files (and any configured additional sources), then rewrites HIPPOCAMPUS.md with a fresh synthesis:
- **Top of Mind** — 3-5 highest-priority items, rewritten every sync
- **Open Threads** — active work, persists until resolved
- **Commitments** — who owes what, with staleness flags
- **Recent Sessions** — rolling conversation log
### Graduation
When a pattern persists in the hippocampus across multiple cycles, it's a candidate for permanent memory. Use the `hippocampus_graduate` tool (or ask your agent) to promote it to MEMORY.md.
## Configuration
### Zero config (single agent)
```json
{
"plugins": {
"entries": {
"hippocampus": {}
}
}
}
```
### Full config reference
```json
{
"plugins": {
"entries": {
"hippocampus": {
"config": {
"enabled": true,
"rollingWindowDays": 14,
"targetSizeChars": { "min": 3000, "max": 5000 },
"contextInjection": {
"enabled": true,
"priority": 50,
"excludeAgents": []
},
"synthesis": {
"outputSections": ["top_of_mind", "open_threads", "commitments", "recent_sessions"],
"domainFraming": "General-purpose working memory"
},
"graduation": {
"enabled": true,
"persistenceDaysThreshold": 14,
"autoSuggest": true,
"maxMemorySizeChars": 15000
},
"agents": {
"cyclawps": {
"domainFraming": "Platform-centric. Lead with system health, cron reliability, and infrastructure state.",
"sources": [
{ "id": "health", "path": "artifacts/reports/health-check/", "label": "Health reports", "whatToExtract": "System state, disk, memory, uptime", "windowed": true }
],
"outputSections": ["top_of_mind", "open_threads", "commitments", "recent_sessions", "cron_health"]
}
}
}
}
}
}
}
```
### Per-agent sources
Agent sources are **additive** — `memory/` is always included as the first source. Additional sources are appended. Each source can include `whatToExtract` guidance:
```json
{
"id": "charter",
"path": "CHARTER.md",
"label": "Strategic charter",
"whatToExtract": "Current priorities, goal progress, pending decisions",
"windowed": false
}
```
### Companion config file
For advanced per-agent customization, create `hippocampus-sync.config.md` in the agent's workspace. The synthesis skill reads this file first for domain framing, source tables, and writing quality guidance. The setup wizard generates this file automatically.
## Agent tools
| Tool | Description |
|------|-------------|
| `hippocampus_setup` | Conversational onboarding. Scans workspaces, previews synthesis, walks through configuration. |
| `hippocampus_graduate` | Promotes a durable learning from HIPPOCAMPUS.md to permanent MEMORY.md. |
## Coexistence
Hippocampus works alongside other OpenClaw plugins:
- **lossless-claw**: Hippocampus is NOT a context engine. It uses `before_prompt_build` hooks, which lossless-claw respects during context assembly.
- **memory-core**: Hippocampus writes to `memory/` and `HIPPOCAMPUS.md`. memory-core indexes these files automatically.
- **Any other plugin**: No conflicts. Hippocampus only reads/writes markdown files in agent workspaces.
## Development
```bash
# Install dependencies
npm install
# Run tests (47 tests)
npm test
# Type check
npx tsc --noEmit
# Link for local development
openclaw --dev plugins install --link /path/to/hippocampus
openclaw --dev gateway run
```
See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the full development guide and [docs/TESTING.md](docs/TESTING.md) for end-to-end testing instructions with a dev OpenClaw instance.
## License
MIT
tools
Comments
Sign in to leave a comment