| name | memory |
| description | Per-role persistent memory for Octobots roles. Curated typed entries (facts, preferences, decisions) and append-only daily logs (episodic, "what did I do today"). Use when the user says "remember this", "what did you learn yesterday", "log this", or whenever you discover something worth keeping across sessions. |
| license | Apache-2.0 |
| compatibility | Requires Python 3.10+ (stdlib only, no pip dependencies) |
| metadata | {"author":"octobots","version":"0.1.0"} |
Memory
Persistent per-role memory. Two complementary stores under .agents/memory/<role>/:
- Curated — typed entries (
<name>.md with frontmatter) plus an index MEMORY.md. For facts that should survive across many sessions: user preferences, project decisions, feedback, references.
- Daily log —
daily/YYYY-MM-DD.md, append-only timestamped lines. For episodic recall: what you did, what the user said, transient context. Bounded by date so it doesn't grow forever.
A snapshot.md is regenerated at every role launch combining the index and the last few days of daily log. Roles @import it from their AGENT.md so memory is auto-loaded into the system prompt at session start — no manual reads needed.
Quick Start
Resolve your role from env OCTOBOTS_ID.
python octobots/skills/memory/scripts/memory.py log "Discussed Q2 roadmap with user; agreed to defer mobile work"
python octobots/skills/memory/scripts/memory.py write user_timezone \
--type user --description "User's timezone and quiet hours" \
--content "User is in CET (UTC+1). Quiet hours: 22:00–08:00."
python octobots/skills/memory/scripts/memory.py read --days 3
python octobots/skills/memory/scripts/memory.py snapshot
All commands accept --role <name> to override OCTOBOTS_ID.
When to log vs. write
log — anything happening now that you'd want to remember tomorrow but probably not next month. User's mood, what task you're mid-flight on, a one-off observation. Cheap.write — durable facts, preferences, decisions, lessons. Expensive — costs an index entry. Should be re-readable in 6 months and still useful.
If unsure: log it. The next snapshot will surface it; you can promote to a curated entry later.
Memory types (curated only)
| Type | What goes here |
|---|
user | Who the user is, role, expertise, preferences |
feedback | Corrections and validated approaches the user gave you. Include the why |
project | Goals, deadlines, constraints, in-flight initiatives. Decay fast — re-verify before acting |
reference | Pointers to external systems (Linear projects, Slack channels, dashboards) |
Auto-load
Roles import their snapshot via @.agents/memory/<role>/snapshot.md at the top of their AGENT.md. The path is IDE-neutral — .agents/ works under Claude Code, Cursor, Gemini CLI, Copilot CLI, Windsurf, or Octobots. Claude Code resolves the import at session start so curated entries and recent daily logs are part of the system prompt automatically. The supervisor regenerates snapshot.md before every role spawn.
