Memory system

MindStone for Claude Code uses a file-based memory system: structured Markdown files in orchestrator/memory/ with YAML frontmatter that carries weighting metadata.

Memory files

Each memory file is a Markdown document:

---
name: feedback_careful_with_tests
description: Be careful about breaking existing tests when refactoring
type: feedback
tags: [testing, refactoring]
projects: [project-a]
created: 2026-03-15
last_applied: 2026-04-12
hits: 7
prevented: 3
half_life_days: 30
critical: false
evergreen: false
---

# Be careful with test refactoring

When refactoring shared utilities, always run the full test suite first...
[memory content]

Frontmatter fields

Field	Type	Purpose
`name`	string	Unique identifier (also the filename prefix)
`description`	string	One-line summary for the memory index
`type`	string	`feedback`, `project`, `reference`, or `design`
`tags`	array	Topic tags for grouping and filtering
`projects`	array	Project associations (empty = applies to all)
`created`	date	When the memory was first created
`last_applied`	date	When the memory was last injected into context
`hits`	integer	Times this memory was retrieved and useful
`prevented`	integer	Times this memory demonstrably prevented a mistake
`half_life_days`	integer	Decay rate (higher = stays relevant longer)
`critical`	boolean	Critical memories always inject, never decay
`evergreen`	boolean	Evergreen memories never decay

SCRI weighting in practice

The retrieval score for a memory is calculated from:

score = semantic_similarity × (1 + hits × 0.1) × (1 + prevented × 0.3) × recency_factor

Where recency_factor decays from 1.0 to near-0 over half_life_days days.

Practical implications:

A memory with hits: 7, prevented: 3 ranks much higher than a similar memory with hits: 0
A critical: true memory always injects regardless of similarity score
An evergreen: true memory (like reference_*.md files) never decays away

Memory index (MEMORY.md)

orchestrator/memory/MEMORY.md is the index file — one-line pointers to every memory file:

# Memory Index

## Critical feedback (always injected)
- [feedback_never_do_x.md](feedback_never_do_x.md) — ABSOLUTE RULE: never do X
- [feedback_verify_first.md](feedback_verify_first.md) — Always verify before acting

## Standard feedback
- [feedback_careful_tests.md](feedback_careful_tests.md) — Be careful with test refactoring

## Projects
- [project_current.md](project_current.md) — Current sprint context

## Reference (evergreen)
- [reference_architecture.md](reference_architecture.md) — System architecture notes

The SessionStart hook reads MEMORY.md to know what’s available and which files to inject by default. Critical memories (tagged critical: true) are always injected; others are only injected when their SCRI score is high enough.

File naming conventions

feedback_<topic>.md       # Corrections, rules, learned behavior
project_<name>.md         # Per-project context (decays)
reference_<topic>.md      # External system facts (evergreen)
design_<topic>.md         # Design decisions and rationale

Adding new memories

The /checkpoint command creates new memory files as part of its synthesis step. You can also create them manually:

cat > orchestrator/memory/feedback_new_pattern.md << 'EOF'
---
name: feedback_new_pattern
description: New pattern discovered during sprint
type: feedback
tags: [performance, database]
projects: []
created: 2026-04-24
last_applied: 2026-04-24
hits: 0
prevented: 0
half_life_days: 30
critical: false
evergreen: false
---

# New pattern

[Content here]
EOF

After adding a new file, re-run the indexer to add it to the vector store:

python3 orchestrator/hooks/indexer.py