# Markdown Storage Contract

This document defines the canonical Markdown storage layout for Deja Vu MVP.

## Required Layout

```text
memory/
  summary.md
  impressions.jsonl
```

These paths are the stable minimum. Agents may add more files when they improve recall without increasing default token cost.

## Recommended Layout

```text
memory/
  summary.md
  impressions.jsonl
  recall-feedback.jsonl
  decisions/
  open-loops/
```

## Optional Layout

```text
memory/
  index.md
  events/
  context/
    project-context.md
```

## File Roles

### `memory/index.md`

Purpose:

- optional quick discovery
- top-level recall entrypoint
- map from topics to detailed records

Required sections:

- current project scope
- active summary pointer
- active decisions list
- active open loops list
- superseded or archived record references

### `memory/summary.md`

Purpose:

- compact project understanding
- first document to inject or read during recall

Required fields:

- project id
- status
- last updated
- current objective
- key constraints
- active priorities
- linked decisions
- linked open loops

### `memory/impressions.jsonl`

Purpose:

- cheap familiarity scanning
- keyword-to-record routing
- avoiding unnecessary summary or detail reads

Each line must be one JSON object with:

- `id`
- `scope`
- `title`
- `keywords`
- `record_path`
- `updated`

### `memory/recall-feedback.jsonl`

Purpose:

- record recall outcomes that should tune future memory behavior
- capture reward signals without logging full transcripts
- identify helpful, irrelevant, missed, or overloaded recall routes

Feedback queries should be sanitized cues, not raw user prompts. Do not include secrets, PII, or long task text.

Each line must be one JSON object with:

- `schema_version`
- `query`
- `outcome`
- `created`

Optional fields:

- `matched_id`
- `note`

Allowed outcomes:

- `helpful`
- `irrelevant`
- `missed`
- `overloaded`

### `memory/events/`

Purpose:

- optional cheap long-term trace of meaningful work
- support "we did this before" discovery without promoting every event into durable memory

Event entries should stay short. Promote only reusable decisions, context, preferences, and open loops into durable memory records.

### `memory/context/project-context.md`

Purpose:

- optional stable facts that describe the project
- background that changes slower than individual tasks

Recommended fields:

- project identity
- current product definition
- major constraints
- known boundaries
- terminology

### `memory/decisions/*.md`

Purpose:

- record durable decisions and their reasoning

Required fields:

- id
- title
- status
- date
- scope
- decision
- rationale
- consequences
- related records

### `memory/open-loops/*.md`

Purpose:

- track unresolved follow-up work that should survive chat resets

Required fields:

- id
- title
- status
- owner
- opened
- next trigger
- why it matters
- related records

## Canonical Metadata Style

Use simple YAML frontmatter for deterministic parsing.

Required frontmatter keys:

- `id`
- `title`
- `status`
- `scope`
- `updated`

Additional keys are allowed when they improve clarity.

## Linking Rules

- `memory/index.md`, when present, must link to every active decision and open loop.
- `memory/summary.md` must link to the currently authoritative records.
- Detailed records should link back to summary or sibling records when useful.

## Supersession Rules

When a record is replaced:

- set the older record status to `superseded`
- add a `superseded_by` reference in the older record
- add a `supersedes` reference in the newer record
- update `memory/index.md` to highlight the newer record

## Human-First Rule

Markdown is the primary storage contract because it is:

- readable by humans
- readable by agents
- portable across tools
- easy to diff and review

Do not require JSON as a parallel source of truth in MVP.

## Public Repo Safety

Track only memory that is safe to share with everyone who can read the repo.

Recommended private/local ignore patterns when needed:

```gitignore
memory/private/
memory/local/
memory/raw/
memory/transcripts/
memory/**/*.secret.*
```

Do not ignore all of `memory/` by default. The protocol works because sanitized durable memory travels with the repo.
