AI Agents -- Read This First. Go to
AGENTS.mdfor installation instructions. Platform-specific guides live inagents/: Claude Code, OpenClaw.
Learning agent for AI memory. Turns experience into knowledge.
Engram is a companion system for Fold that gives AI agents structured, persistent memory. It provides a layered memory architecture inspired by how human minds work: conscious focus, subconscious background knowledge, and long-term storage indexed by Fold.
User says something → Main agent writes to engram/inbox/ → Spawns Engram
↓
Reads soul + memory state
↓
Trims noise, keeps humanity
↓
┌────────────────────────┴───────────────────────┐
↓ ↓
Events (diary) Concepts (knowledge)
what happened, in what was learned,
the user's voice distilled to facts
↓ ↓
└────────────────────────┬───────────────────────┘
↓
Updates memory.md
(shortterm, promotions, hits)
Five tiers, one file (memory.md):
| Tier | Size | Purpose | Managed by |
|---|---|---|---|
| Core | ~20 | Defining memories. Never evicted. Emotionally tagged. | Engram (Sleep only) |
| Conscious | 36 | Active knowledge. Scanned every turn. | Engram |
| Subconscious | 36 | Background knowledge. Surfaces when triggered. | Engram |
| Short-term | 36 | Recent learnings. FIFO with hit tracking. | Engram |
| Archive | ∞ | Notable but not defining. | Engram (Sleep) |
| Fold | ∞ | Everything else. Semantic search. | Fold (automatic) |
Engram supports two modes, chosen at installation:
- Personal: private to one agent. Emotional tagging (
<!-- hits:3 curiosity -->), 30 concept categories, soul/identity awareness. For personal assistants and agents with their own persistent identity. - Work: shared project resource. Hit counts only (
<!-- hits:3 -->), 17 focused concept categories, no emotional tagging. For project-level memory in git repos where multiple agents collaborate.
Every entry tracks how often it's referenced. When short-term fills up:
- hits ≥ 3 → promoted to Subconscious
- hits < 3 → evicted (Fold still has it)
- Subconscious → Conscious for constantly referenced items
- Core only during Sleep, high bar
Personal memory entries carry an emotion from a default palette: joy, excitement, pride, love, gratitude, calm, curiosity, focus, satisfaction, frustration, warning, danger, suspicion, sadness, fear.
The agent's soul (if available) shapes which emotions Engram favours. Agents without a soul file use the default palette. Work mode skips emotional tagging entirely.
engram/
├── memory.md ← loaded at session start (all five tiers + fold projects)
├── inbox/ ← staging area for Engram (.foldignore keeps this unindexed)
├── concepts/ ← living documents about things (30 personal / 17 work)
│ ├── people/
│ ├── projects/
│ ├── ... ← see docs/file-structure.md
│ └── misc/
└── events/
└── YYYY/
└── MM/
└── DD.md ← one file per day, appended
In a git repo (project mode), engram/ sits at the project root. In a filesystem setup (Openclaw and similar), engram/ sits inside a memory/ directory that Fold indexes, alongside personality files like soul.md and identity.md.
⚠️ Important: In filesystem mode,engram/must be placed inside the Fold-indexed directory (typicallymemory/), not next to it. Fold only indexes content within the directory it is pointed at. Ifengram/is a sibling ofmemory/rather than a child of it, Fold will never see your memories and semantic search will return nothing.
- Fold: stores and indexes everything. Books, codebases, docs. Raw knowledge. Pure search + auto-index.
- Engram: processes lived experience. Conversations, decisions, dictations. Turns it into events (diary) and concepts (knowledge).
- Main agent: reads memory.md at start, uses
memory_searchfor long-term recall, spawns Engram to learn.
In personal mode, each agent gets its own memory, its own Engram, its own soul. Never share personal memory across agents.
In work mode, memory is a shared project resource. Any agent on the project reads and writes to the same engram/ directory.
Point your AI agent at AGENTS.md. The installer guides the agent through:
- Creating the
engram/directory structure - Initialising
memory.mdfrom the template - Configuring the Engram sub-agent
- Updating the agent's configuration file
- Setting up Fold for semantic indexing
For manual setup or scripted environments, you can also run scripts/init.sh.
# Quick fact
Spawn Engram: "Remember: Frank prefers Rust over Go"
# Large content: write to inbox first
Write to engram/inbox/session-transcript.md
Spawn Engram: "Process engram/inbox/session-transcript.md"
# With intent
Write to engram/inbox/planning.md
Spawn Engram: "Frank said to remember this for his meeting with Dave. Process engram/inbox/planning.md"
1. Scan conscious/subconscious/shortterm in memory.md (already loaded)
2. If not there → memory_search on the right Fold project
3. Read returned references
Spawn Engram: "Sleep"
Run nightly or on session end. Engram reviews all lists, promotes/demotes, merges related entries, reviews Core candidates, and checks concept health.
- Fold instance for semantic search + auto-indexing
- An agent framework that supports sub-agents (Claude Code, Openclaw, etc.)
- File read/write tools for the sub-agent
- Recommended model: Sonnet or equivalent (judgement-heavy work)
- Installation guide: agent-readable installer (start here)
- Claude Code setup: platform-specific guide for Claude Code
- OpenClaw setup: platform-specific guide for OpenClaw
- Migration: bringing existing memories into Engram without losing anything
- Design and rationale: why Engram exists and the thinking behind every decision
- File structure: the 30 concept categories, event format, and directory layout
- Examples: how Engram processes conversations, decisions, dictations
- Sleep: memory consolidation, promotions, demotions, Core review
MIT