Why can't I just use markdown files for agent memory?

Markdown files conflate observations with snapshots. When two agents write conflicting values, both edits land silently. There is no schema validation, no conflict detection, and no way to reconstruct entity state at a past moment without building significant application logic on top.

Why can't I just use markdown files for agent memory?

Markdown files conflate observations with snapshots. When two agents write conflicting values, both edits land silently. There is no schema validation, no conflict detection, and no way to reconstruct entity state at a past moment without building significant application logic on top.

Neotoma vs File-Based Memory | Markdown, JSON vs Deterministic State (Markdown)

Q: Can git replace versioned history?

Git versions file snapshots, not entity observations. It can tell you what a file looked like at a commit, but not which observation changed which field or how conflicting writes were resolved.

<!--
  Full-page Markdown export (rendered HTML → GFM).
  Source: https://neotoma.io/pt/neotoma-vs-files
  Generated: 2026-04-01T11:48:38.549Z
-->
# Neotoma vs file-based memory

File-based memory stores state in Markdown, JSON, or similar artifacts. It is portable and human-editable, but provides no schema enforcement, conflict detection, or auditable provenance unless layered on manually. Neotoma stores structured observations and composes entity state via deterministic reducers with formal guarantees.

Markdown and JSON files are the simplest possible memory store for AI agents. They work well for lightweight, single-writer workflows. The question is what happens when requirements grow.

## Why not just use markdown files for agent memory?

File-based memory

File-based memory stores facts as plain text artifacts on disk. Agents read and write files directly, or commit them to git. The format is maximally portable and human-readable. Versioning comes from git, but conflict detection, schema validation, and provenance are not built in.

Neotoma

Neotoma stores append-only observations about entities. Deterministic reducers compose all observations into a single entity snapshot. Every field traces to its source observation, schema validation rejects malformed writes, and conflicting facts are resolved deterministically.

◆

## Guarantee comparison

| Property | File-based memory | Neotoma |
| --- | --- | --- |
| Deterministic state evolution | Not provided | Guaranteed |
| Versioned history | Manual | Guaranteed |
| Replayable timeline | Not provided | Guaranteed |
| Auditable change log | Partial | Guaranteed |
| Schema constraints | Not provided | Guaranteed |
| Silent mutation risk | Common risk | Prevented |
| Conflicting facts risk | Possible risk | Prevented |
| Reproducible state reconstruction | Not provided | Guaranteed |
| Human inspectability (diffs/lineage) | Partial | Guaranteed |
| Zero-setup onboarding | Not provided | Not provided |
| Semantic similarity search | Not provided | Guaranteed |
| Direct human editability | Guaranteed | Not provided |

◆

## When to use which

Use File-based memory when

You have a single agent, simple state, and value being able to open memory in a text editor. Git-based versioning is sufficient for your audit needs, and you do not need conflict resolution or schema enforcement.

Use Neotoma when

Multiple agents or tools write to the same entities. You need schema validation, conflict detection, reproducible state reconstruction, or auditable provenance that goes beyond git commit history.

## Common questions

### Can git replace versioned history?

Git versions file snapshots, not entity observations. It can tell you what a file looked like at a commit, but not which observation changed which field, or how conflicting writes from different agents were resolved. Git versions the output; Neotoma versions the inputs.

### What about structured formats like JSON or YAML?

Structured file formats give you parseable data but not memory guarantees. A malformed edit, an accidental deletion, or two agents writing different values to the same key are all accepted silently. Neotoma validates writes against schemas and rejects invalid data at store time.

### Can I use file-based memory alongside Neotoma?

Yes. You can use files for human-editable configuration and notes while using Neotoma for entity state that needs formal guarantees. They address different layers of the problem.

[Install Neotoma](/install)[All memory models](/memory-models)[FAQ](/faq)