REMEMBER.md Spec v1

Open standard for AI memory configuration. Status: Living Draft · Last updated 2026-05-05

Pitch

AGENTS.md tells your AI how to work. REMEMBER.md tells your AI how to remember. Together they form the markdown duo for portable, tool-agnostic AI configuration — one file for behaviour, one for memory, both human-readable and version-controllable.

Core rules

The file is named REMEMBER.md.
It lives at the root of your brain (or any project that needs overrides).
It is plain markdown. ## Section Name headings delimit blocks.
Seven section names are reserved by the spec (see below). All optional.
An empty file means "use engine defaults". Zero config = it works.
Engines MUST ignore sections they don't understand (forwards-compatible).
Engines MUST NOT auto-modify the file. It belongs to the user.
User rules override engine defaults; project-level overrides global.

Reserved sections

Section	Purpose
`## Capture Rules`	Always-capture / never-capture filters and thresholds.
`## Routing`	Where each kind of content lands in the brain.
`## Processing`	How content is formatted, tagged, summarised.
`## Custom Types`	User-defined entity types beyond the engine's defaults.
`## Connections`	Auto-linking rules and relationship hints.
`## Language`	Multilingual capture and processing preferences.
`## Promotion Thresholds`	Confidence/sources thresholds for promoting beliefs to a pinned section.
`## Templates`	Override engine-default templates per file kind.

Override semantics

Same-name section in your file — content is appended to the engine default.
## Override: <Name> — your content fully replaces the matching default.
Any other heading — passed through verbatim as a user-defined section. Engines ignore unknown sections gracefully.

Engine guarantees

The brain is plain markdown, browseable in any editor (Obsidian, VS Code, …).
Schema is additive: type, freshness, confidence, sources_count, evidence[], counter_evidence[] are optional in v1, not required.
An evolution layer (consolidation, reflection, promotion) is allowed but must be auditable and reversible.
No content leaves the user's machine without explicit consent.

Reference parser (20 lines)

import re

def parse_remember_md(path):
    with open(path) as f:
        text = f.read()
    sections = {}
    for match in re.finditer(
        r'^## (.+)\n(.*?)(?=^## |\Z)',
        text, re.M | re.S
    ):
        name = match.group(1).strip()
        content = match.group(2).strip()
        if content:
            sections[name] = content
    return sections

Reference implementation

The Remember plugin (github.com/remember-md/remember) is the canonical engine. It ships:

A SessionStart hook that loads Persona.md and an AI-driven passive capture nudge
A capture skill triggered by phrases like "remember this:" with live polarity check (positive evidence vs counter-evidence)
A bulk-extraction skill for retroactive session processing
Auto-promote at capture time so Persona.md ## Top Beliefs stays in sync without cron, with bootstrap thresholds for cold-start brains
An evolve skill (recommended weekly) that consolidates entities, reflects on beliefs, and promotes top beliefs to Persona
An auditable evolution log at ~/.local/state/remember/evolution.log

Adopting REMEMBER.md

Tool authors are encouraged to read REMEMBER.md from the project root and apply the rules described above. A 20-line parser (in any language) is enough for v1 compliance. Engines are free to extend with additional sections, as long as they do so under the ## x-* prefix or as ## Override: <name> blocks to avoid name conflicts.

Versioning

The spec is versioned (v1.0, v1.1, v2.0); individual REMEMBER.md files are not.
New section names may be added in minor versions. Removed names: never.
Engines stay forwards-compatible by ignoring unknown sections.

Status & contributions

v1 is a living draft. Implementations, feedback, and competing parser libraries are welcome at github.com/remember-md/remember/issues.

Inspired by .editorconfig (one page, dead-simple, 30+ editors), llms.txt (markdown-native, grassroots), and AGENTS.md (cross-tool agent instructions).