icarus-memory-infra: Icarus Memory Infrastructure: The Agent Memory System That Refuses to Forget Properly
A local-first, Markdown-native memory layer for coding agents that separates private attempts, durable history, and shared truth, so context stays useful instead of stale.
- Icarus is interesting because it treats agent memory as a trust system, not a convenience layer for recall.
- Its three-layer model keeps private attempts, archived sessions, and shared wiki knowledge from collapsing into one stale context blob.
- Supersession is the core idea: memory is versioned, auditable, and explicit about what replaced what.
- The project argues that Markdown on disk is not a fallback from databases, but the right substrate for inspection, portability, and recovery.
The bug isn’t forgetting. It’s remembering the wrong thing.
Coding agents do not just suffer from short context windows. They also inherit their own mistakes. A model can repeat a failed approach because the failure was stored too vaguely, too loudly, or in the same place as the facts it should trust.
That is the real problem Icarus tries to solve. It is not a database for more memory. It is a trust architecture for deciding what should stay private, what should be archived, and what deserves to become shared truth.
Icarus Memory Protocol -- universal agent memory in 50 lines. markdown files in a directory. any framework, any platform, shared memory. includes two-agent reference implementation with Telegram, Slack, and cross-platform recall.
Three layers, three jobs
Icarus breaks memory into Working Memory, Session Archive, and Wiki. That sounds simple until you realize the boundary is the whole point. Working Memory is for active attempts and hypotheses. Session Archive captures the session as a private record. Wiki is where conventions and decisions become shared.
What makes Icarus different is not storage. It is promotion.
The article’s center of gravity is supersession. Icarus does not merely store entries. It records what replaced what. That gives memory a lineage, which matters when an agent revises a plan, changes a convention, or learns that an earlier attempt was wrong.
That lineage is the anti-stale-context move. Failed local attempts are not promoted into shared memory just because they exist. They can stay in the archive as evidence, but they do not contaminate the wiki unless someone explicitly promotes them.
The result feels less like a chat log and more like a flight recorder with a verified public log. You can inspect the trail. You can see which facts were learned, which were superseded, and which are still trusted across agents.
解決策は、ファイルシステム層での統合という、ある意味で最も原始的で、最も確実な方法だった。 私はこれを「Icarus Memory Protocol（イカロス記憶プロトコル）」と名付けた。 太陽に近づきすぎて翼が溶けたイカロスの神話から。 高く飛ぼうとすれば墜落する。 だからこそ、地に足のついた仕組みが必要だという自戒を込めた名前だ。
Markdown on disk is the point
The storage choice is the argument. Icarus uses local files, YAML frontmatter, and date-based paths. That makes memory grep-friendly, portable, and easy to recover after a crash. The repo’s `store.py` leans on atomic writes, which is exactly the kind of boring reliability that agent systems usually lack.
# store.py style pattern
with tempfile.NamedTemporaryFile('w', delete=False, dir=root) as tmp:
tmp.write(render_markdown(entry))
tmp_path = tmp.name
os.replace(tmp_path, target_path) # atomic promotion into placeThis is also why the project feels opinionated in the right way. A human can open the files, diff them, back them up, or sync them with normal tools. The memory layer does not hide inside a service. It stays visible to the people who have to trust it.
Why this beats a generic vector memory stack
| Dimension | Icarus | Vector or graph memory stack |
|---|---|---|
| Storage model | Markdown and JSON files on disk | Indexed embeddings or database-backed graphs |
| Setup complexity | Low | Medium to high |
| Debuggability | High, because files are inspectable | Lower, because state lives behind APIs and indexes |
| Audit trail | Explicit supersession and provenance | Often implicit or reconstructed after the fact |
| Cross-agent sharing | Built around shared wiki promotion | Usually requires extra plumbing |
| Search sophistication | Good enough plus optional hybrid search | Strong semantic retrieval, but heavier operationally |
| Operational burden | Lightweight and local-first | More moving parts and more maintenance |
The trade-off is clear. Vector-heavy systems are better at semantic recall, but Icarus is better at knowing why a piece of memory is trusted. For agent workflows, that difference is not cosmetic. It decides whether the system becomes a useful teammate or just a noisier cache.
Where the project is headed
The MCP server points to the larger ambition. Icarus is trying to become the memory layer that agent tools can standardize around. That is a bigger bet than a file format. It is a claim that context management itself deserves infrastructure.
That is why the project lands. It does not promise perfect recall. It promises accountable recall. In a category crowded with retrieval tricks, that is a sharper and more durable idea.