MemoryCore stores everything as plain, human-editable Markdown. The format is designed to diff cleanly in git, survive hand-edits, and stay readable without any tooling.
.memory/
manifest.json # machine-readable index + schema version (the only non-Markdown file)
README.md # human explainer for the folder
architecture.md # entries of type: architecture
decisions.md # entries of type: decision
conventions.md # entries of type: convention
bugs.md # entries of type: bug
roadmap.md # entries of type: roadmap
One file per entry type; the mapping is fixed. .memory/ is meant to be committed
to git. The generated CLAUDE.memory.md / AGENTS.memory.md export bundles are derived
artifacts and are gitignored by default.
Each entry is one Markdown section: a <!-- memory:entry --> metadata block, a ##
title heading, and the body. The HTML-comment block keeps metadata machine-readable
without polluting the reading experience.
# Decisions
<!-- memory:entry
id: decision-2026-06-08-a1b2
tags: [tooling, build]
status: accepted
created: 2026-06-08T10:12:00Z
updated: 2026-06-08T10:12:00Z
-->
## Use pnpm workspaces
We chose pnpm over npm and yarn for its content-addressable store, strict
dependency resolution, and first-class monorepo workspace support.
**Why:** faster CI installs, no phantom dependencies.
**Alternatives considered:** npm workspaces (slower), yarn berry (PnP friction).| Field | Required | Notes |
|---|---|---|
id |
yes | Stable id: <type>-<YYYY-MM-DD>-<4-char-random>, e.g. bug-2026-06-08-9f3c. |
tags |
no | [a, b, c]; lowercase, kebab-case. |
created / updated |
no | ISO 8601 timestamps. |
status |
no | Decisions: proposed | accepted | superseded. |
severity |
no | Bugs: low | medium | high | critical. |
confidence |
no | low | medium | high — how settled the knowledge is. |
links |
no | Related entry ids, URLs, or file paths. |
The title is the first ## heading after the block; the body is everything until the
next entry block or end of file.
idis the only strictly required metadata key; everything else defaults gracefully.- A section without a
memory:entryblock is treated as human-authored prose: preserved on disk, but not indexed as a structured entry. This makes hand-editing safe. - Entries are stored newest-first under each type heading.
- Line endings are normalized to
\non write;\r\nis tolerated on read.
A lightweight index/cache for fast query and export without re-parsing every file:
The manifest is rebuildable from the Markdown at any time. If it ever disagrees with the Markdown files, the Markdown is the source of truth — counts and entries are re-derived defensively on read.
.memory/*.md files are just Markdown — open, edit, and commit them in any editor. Keep
the <!-- memory:entry --> block intact (especially id) so the entry stays indexed.
Prose you add outside an entry block is preserved and surfaced in exports, but not
treated as a structured entry.
{ "schemaVersion": 1, "version": "0.1.0", "createdAt": "2026-06-08T10:00:00Z", "updatedAt": "2026-06-08T10:12:00Z", "entries": [ { "id": "decision-2026-06-08-a1b2", "type": "decision", "title": "Use pnpm workspaces", "tags": ["tooling", "build"], "file": "decisions.md", "created": "2026-06-08T10:12:00Z", "updated": "2026-06-08T10:12:00Z" } ], "counts": { "architecture": 0, "decision": 1, "convention": 0, "bug": 0, "roadmap": 0 } }