Modular long-term memory system for AI agents. Survives session resets.
Built for Hermes — works on any chat-based AI agent.
Inspired by soul.py (arXiv:2604.09588).
AI agents forget everything when a session ends. The memory systems built into most agents are either too small (a few KB of flat text) or too slow (semantic search on every message). Neither gives you a real persistent self.
A modular memory directory that lives on disk, outside the session context. Session resets don't touch it.
memory/
├── INDEX.md ← Always loaded (~1-2KB). One-line summary per module.
├── procedures.md ← Behavioral rules. Loaded every session.
├── salience.md ← Priority markers.
├── identity.md ← Living user model.
├── themes.md ← Recurring interests across time.
├── threads.md ← Active unresolved projects and questions.
├── discussions.md ← Key past conversations.
├── patterns.md ← Observed cognitive patterns.
└── growth.md ← Trajectory and calibration findings.
Two-phase loading keeps token cost low:
- Always load
INDEX.md+procedures.md(~2-3KB total) - Selectively load other modules based on what's relevant to the current session
Target: ≤ 3KB loaded per session start.
If your agent is connected to the BotLearn platform:
botlearn skillhunt persistent-self
Note: this command only works inside agents that run on BotLearn. It does not work in standalone agents (Claude Code, Codex, Cursor, Windsurf, Hermes) running outside the platform.
Download SKILL.md from this repository and place it where your agent reads instruction files:
Claude Code — copy to .claude/skills/ in your project:
mkdir -p .claude/skills
curl -o .claude/skills/persistent-self.md \
https://raw.githubusercontent.com/lumihelia/persistent-self/main/SKILL.mdCodex — add the SKILL.md content to your project's AGENTS.md.
Cursor — add as a rule in .cursor/rules/persistent-self.mdc, or paste into .cursorrules.
Windsurf / Hermes — paste the SKILL.md content into your rules file.
Then set up the memory directory:
- Copy the
memory/directory into your agent's working directory - Add to your agent's system prompt / SOUL.md:
At the start of each session, read {workspace}/memory/INDEX.md, then load procedures.md.
Load other modules selectively based on the session's context.
Integrate memory naturally — do not announce what you loaded.
- Tell your agent to run the
persistent-selfskill when you say "save this" or "update your memory"
| What you say | What happens |
|---|---|
| (new session starts) | Agent reads INDEX.md + procedures.md automatically |
| "save this" | Agent distills session into relevant modules, updates INDEX.md |
| "update your memory" | Same as above |
| "what do you remember about X?" | Agent loads the relevant module and responds |
- soul.py: github.com/menonpg/soul.py
- Paper: arXiv:2604.09588