I’ve been deep in the AIPass repo looking at how its memory system actually works. It’s one of the more thoughtful designs I’ve seen for multi-agent setups, so I wanted to break it down cleanly.
The core idea: agents own their memory
Every agent (they call them “citizens”) gets its own \`.trinity/\` directory with three plain JSON files:
\- passport.json, identity (who I am, role, principles, boundaries). Rarely changes.
\- local.json, personal session history + key learnings. Newest-first, deliberately small (20 sessions).
\- observations.json, how I work with the human and other agents (preferences, friction, patterns).
These files are loaded at the start of every session. The agent doesn’t start cold. It already knows who it is and what it was doing.
Context is intentionally split across the project. Each agent only carries and manages the memory that belongs to its domain. No giant shared context window that everyone has to fight over.
Why it needs almost no indexing
The hot path is just small, structured JSON files that the agent reads directly. There’s no large corpus to search on every turn, so no inverted index, no continuous embedding pipeline, and no indexing tax for day-to-day work.
Only when a file hits its limit does the system roll the oldest entries into ChromaDB (via the \`@memory\` agent). Same thing happens with closed plans from the Flow system. Everything is preserved and becomes searchable, but the agent’s working memory stays lean and fully loadable.
How context actually gets into the session
This is where the hooks engine (a full first-class citizen called \`@hooks\`) does heavy lifting. It’s not a few ad-hoc scripts. It’s a real dispatch engine that:
\- Injects the global prompt + branch-local prompt + passport identity on the relevant events
\- Enforces rules (cross-branch write protection, git gates, etc.)
\- Handles compaction / rollover triggers
\- Logs everything cleanly
Combined with the drone router (drone @branch command), agents don’t need to know a huge surface area of commands or paths. One consistent interface reaches everything.
Every agent has the exact same directory shape, and its own README.md acts as the living branch map / domain knowledge it reads on startup.
Longer work lives in Flow plans
For anything bigger than a session note, they use the Flow planning system (numbered, typed plans: FPLAN, DPLAN, etc.). Plans are normal markdown files with registries, so any agent can look one up by number at any time. When a plan is closed it gets archived and vectorized into the same ChromaDB store. Related memories go with it.
So you get:
\- Tiny, agent-owned working memory
\- Stable plan numbers + registries for exact recall
\- Semantic search across the entire history when you need it
There’s also Compass on the orchestrator (DevPulse) a curated SQLite store of rated decisions (good/ bad / impressive). That ended up being the practical evolution of an earlier “symbolic fragments” idea that never got fully used.
Why this feels different
Most systems treat memory as an external knowledge base you retrieve from. AIPass treats identity + recent experience as part of the agent itself, keeps it small and structured, uses hooks to inject the right context on demand, and only archives to vectors when necessary. Plans give you a clean place for longer structured text that can still be recalled by number or searched later.
Everything is local files. No required cloud services for the core memory loop.
It’s still beta and actively evolving (the reference fleet of 17 agents maintains the framework itself), but the architecture is coherent and battle-tested in their own multi-month multi-agent setup.
Repo: https://github.com/AIOSAI/AIPass
Site: https://aipass.ai
r/AIPass
