DEV Community: Dmytro Halichenko

Five Components of Agent Memory, Implemented in Plain Markdown

Dmytro Halichenko — Mon, 04 May 2026 21:05:53 +0000

An agent memory system, to actually be useful, has to do five things: persist information across sessions, give it structure, support retrieval, allow writeback, and handle forgetting.

Most current implementations cover two or three of these. Vector databases nail retrieval but have no structure a human can read. Prompt files like .cursorrules give you persistence and a thin slice of structure but nothing else. Conversation history scrolls past the context window and is gone.

This post walks through the five components and shows how IWE implements each one. No vector database. No proprietary index. The substrate is a directory of markdown files.

The substrate

IWE is a Rust binary that treats a directory of markdown files as a knowledge graph. Links between files are edges. A link on its own line — [Authentication](auth.md) — is an inclusion link, which establishes a parent-child relationship. Notes can have multiple parents. The graph is rebuilt from the files on every change; the files are always the source of truth.

Agents talk to the graph through a CLI (iwe) or an MCP server (iwec). Humans talk to it through their editor — VS Code, Neovim, Zed, Helix — over LSP.

That's the whole architecture. Now the five components.

1. Persistence

Memory lives as .md files in a directory you choose. It survives sessions, restarts, OS reinstalls, and IWE itself — uninstall the binary tomorrow and your memory is still there, readable in any text editor. Git versions it. rsync backs it up. You already know how to operate it.

Compare to a vector DB or a proprietary blob format: if the vendor changes the format, your memory is stranded.

2. Structure

The structure is the graph. Headers define sections. Inclusion links define hierarchy. Reference links define cross-references. The same note can appear under multiple parents — "Performance Optimization" can live under both Frontend and Backend without duplication.

What structured memory needs — entities, facts, decisions, relationships, temporal context — in IWE these are just notes with links. An entity is a note. A decision is a note linked from the project that made it. A relationship is an inclusion link. Temporal context is git log.

This isn't a clever encoding. It's the boring observation that markdown has always been a graph format, and humans have always written in it.

3. Retrieval

IWE exposes the graph through a query language that reads like Mongo's filter syntax but runs against markdown files:

iwe find "authentication"                           # fuzzy search across titles
iwe find --filter 'status: draft, priority: {$gte: 8}'  # frontmatter predicates
iwe find --included-by projects/alpha:0             # everything under alpha's subtree
iwe find --included-by projects/alpha:0 \
         --references people/dmytro \
         --filter 'status: draft'                   # compose structure + fields

The filter operators are the ones you already know: $eq, $ne, $in, $gt/$gte/$lt/$lte, $exists, $and, $or, $not. On top of that, four structural anchors walk the graph's two edge types: --includes, --included-by for hierarchy, --references, --referenced-by for cross-references. Stack them to compose multi-edge queries — "drafts under this project that mention this person" is three flags, not a join.

For navigating, retrieve fetches a note plus its descendants to a given depth, tree shows the hierarchy, squash flattens a subtree into one document. Projection (--project title,status), sorting (--sort modified_at:-1), and limits round it out. count gives you an integer instead of results.

Retrieval is deterministic graph traversal, not similarity search. The structure the human wrote is the retrieval signal. When the agent gets wrong context, you trace which link brought it in and fix the graph.

4. Writeback

The agent writes back the same way you do. Create a note, link it in, done. But writeback goes further than append-only — the same query language that drives reads also drives mutations:

iwe update -k meeting-notes --set status=reviewed --set priority=3
iwe update --filter 'status: draft, reviewed: true' \
           --set status=published \
           --unset draft_notes

update takes a filter or a key, applies --set and --unset to every match, and rewrites the frontmatter in place. The agent can promote a batch of drafts, tag a set of notes, or adjust priorities across a project — the same filter it used to find the notes is the one it uses to change them.

The MCP server exposes the same operations as tools: create, update, extract (split a section into its own note), inline (pull a referenced note back in), attach (link a note under a new parent). extract and inline let the agent refactor memory the same way a developer refactors code — a note that's grown too long gets split, small notes that belong together get inlined into a summary.

This is what separates real memory from RAG: the agent can read, write, query, and restructure. One source of truth, no sync layer.

5. Forgetting

This is the hardest one. IWE now has a first-class delete with the same filter language:

iwe delete --filter 'status: archived'
iwe delete --filter '{type: scratch, modified: {$lt: "2026-01-01"}}'

Delete is reference-aware: inclusion links to removed notes are cleaned up automatically, inline links are flattened to plain text. Nothing dangles. --dry-run previews without writing. Git means nothing is truly lost — deletions are commits you can reverse.

The full forgetting loop: iwe stats surfaces orphan nodes, dead links, and graph density. iwe find --roots shows unlinked documents — candidates for archival. extract and inline let you summarize subtrees into higher-level notes and archive the details. delete prunes what's no longer needed. The agent can run this loop autonomously: find stale notes, summarize, prune, commit.

Not as elegant as automatic temporal decay, but every step is auditable and reversible.

What this buys you

For agent memory specifically, plain markdown files have a property no vector DB can match: the agent and the human read the same bytes. There is no translation layer where the human's mental model can drift from the agent's stored representation. When the agent surfaces a surprising response, you grep the directory and find out why.

The architectural shape — a human-editable instruction layer, a structured memory layer, a graph view both humans and agents share — is showing up in several places right now. IWE is one open-source implementation of it. The binary is on GitHub, on Homebrew, on crates.io. Point an agent at it and try.

Markdown Knowledge Graph for Humans and AI Agents

Dmytro Halichenko — Sat, 21 Mar 2026 17:13:06 +0000

You accumulate knowledge constantly — notes, docs, project decisions, things you'll need to remember later. AI agents could help you work with all of this. But how do you give them access to what you know?

There's a growing industry around "agent memory" — vector databases, embedding pipelines, retrieval systems. But for personal and project knowledge, the answer might be simpler: plain Markdown files.

The Problem with Agent Memory

The amount of knowledge and context we need to operate with grows exponentially. Codebases expand. Documentation multiplies. Every project accumulates decisions, patterns, and tribal knowledge that's hard to keep in your head — or fit in a context window.

AI agents are supposed to help. Every framework now ships with some form of memory management. LangChain has memory modules. CrewAI has knowledge sources. AutoGPT writes to files. The common pattern: agents need persistent, structured storage that survives beyond a single conversation.

The dominant approach uses vector embeddings. Store memories as embeddings, retrieve via semantic similarity, inject into context. It works, but it creates a problem: the agent's knowledge becomes opaque.

When your agent "remembers" something, where does that memory live? In a vector database you can't easily read. In embeddings you can't edit by hand. The agent has knowledge, but you can't see it, verify it, or share it.

A Different Approach

What if your notes and your agent shared the same knowledge base?

This is the idea behind IWE — a tool that treats Markdown as a knowledge graph accessible to both you and your AI agents. You edit in your preferred text editor with full LSP support. Your agent queries the same files through a CLI. Same source of truth, no sync.

How It Works

IWE consists of two components:

An LSP server (iwes) that integrates with VS Code, Neovim, Zed, and Helix
A CLI (iwe) for programmatic access — the part AI agents use

The core insight: your text editor already has a protocol for structured document access. The Language Server Protocol gives you completions, go-to-definition, references, and code actions. IWE implements LSP for Markdown knowledge bases.

The CLI as Agent Interface

The iwe CLI exposes the same knowledge graph to command-line tools:

iwe find "authentication"

iwe retrieve -k docs/auth-flow

iwe retrieve -k docs/auth-flow --depth 2

iwe retrieve -k docs/auth-flow --dry-run

An AI agent using Claude Code, Cursor, or any tool that can execute shell commands gets structured access to your knowledge base. No embeddings. No vector database. Just Markdown files with a query interface.

Key flags:

Flag	Description
`--depth N`	Follow inclusion links N levels deep
`-c N`	Include N levels of parent context
`-e KEY`	Exclude already-loaded documents
`--dry-run`	Check document count and size before fetching

The --depth flag is particularly useful. It follows inclusion links and inlines child documents, giving the agent transitive context in a single retrieval call.

Inclusion Links: Structure Without Folders

What makes graph traversal work is a simple concept: inclusion links.

An inclusion link is a markdown link placed on its own line:

# Photography

[Composition](composition.md)

[Lighting](lighting.md)

[Post-Processing](post-processing.md)

When a link appears on its own line, it defines structure: "Photography" becomes the parent of the linked documents. Unlike folder hierarchies, a document can have multiple parents:

Frontend Development
├── React Fundamentals
├── Vue.js Guide
└── Performance Optimization

Backend Topics
├── Database Design
└── Performance Optimization  ← same document, multiple parents

This is polyhierarchy — structure without the limitations of folders. Context flows from parent to child. When you retrieve a document with depth, IWE follows these links to pull in child content.

Why this matters vs alternatives:

Folders: Force single placement. "Performance Optimization" can't live in both frontend and backend directories.
Tags: No structure, no ordering, no hierarchy within categories.
Inclusion links: Multiple parents, explicit ordering, annotations alongside links.

What This Enables

This approach gives you context engineering — control over exactly what enters the context window.

When an agent needs to understand your authentication system:

iwe retrieve -k docs/auth --depth 2

It gets back structured Markdown containing:

The auth document itself
Child documents expanded inline
Parent context and backlinks

This is deterministic retrieval. No embedding similarity thresholds. No "maybe relevant" results. The agent gets exactly the documents in your knowledge graph that connect to the topic.

Additional benefits:

Version-controlled knowledge — Git tracks every change
Transitive context in one command — no recursive API calls
Readable, editable, portable — it's just Markdown

The Tradeoff

IWE isn't a replacement for every memory approach:

Best for:

Structured knowledge (technical docs, project specs, reference material, task managenet)
Developer workflows with text editor/CLI comfort
Knowledge you want to read, edit, and version control

The key insight: this isn't "agent memory" bolted onto your workflow. It's your knowledge base — the one you already maintain for yourself — made accessible to agents when you want their help.

You remain in control. The files are yours, readable and editable. Agents become collaborators that can navigate your knowledge, not black boxes that store it.

Getting Started

IWE is open source and available on GitHub. See the Get Started guide for installation and setup instructions.