Memory Trail v1.0

Open-source decision memory and session logging for AI-assisted development.

"Checkpoints track WHAT changed. Memory Trail tracks WHY."

---

The Problem

AI coding assistants make decisions but don't remember why. Each session starts fresh.

Session 1: "Should I cache images locally?" → Agent caches images
Session 2: "Should I cache images locally?" → Agent caches images again
Session 3: User discovers TOS violation, deletes cache
Session 4: "Should I cache images locally?" → Agent caches images (forgot again)

The agent isn't malfunctioning. It simply has no memory of past decisions.

Git tracks WHAT changed. Nobody tracks WHY.

Tool	Tracks
Git	Code diffs — WHAT changed
Changelog	Release notes — WHAT shipped
Memory Trail	Decision rationale — WHY it changed

---

What Is Memory Trail?

Memory Trail is an open-source persistence layer for AI-assisted development.

• Memory — Decisions persist across sessions
• Trail — Follow the breadcrumbs back to understand WHY

Two Components

Component	Purpose	Format
Decision Memory	Architectural constraints agents must follow	docs/DECISION_MEMORY.md
Session Logs	Per-task action traces	docs/sessions/SES-YYYY-MM-DD-NNN.md

With Memory Trail

Session 1: Agent checks Decision Memory → [DEC-001] Use PostgreSQL
Session 2: Agent checks Decision Memory → [DEC-001] Use PostgreSQL
Session 3: Agent checks Decision Memory → [DEC-001] Use PostgreSQL
(Constraint persists across all sessions)

---

Quick Start

Option 1: Claude Skills (claude.ai / Claude Desktop)

1. Download memory-trail.zip
2. Go to Settings → Features → Skills → Add
3. Upload the zip file
4. Claude will now track decisions and sessions

Option 2: Claude Code / Roo Code

1. Copy SKILL.md to your project's skills folder
2. Copy templates from assets/ to your project:

   cp assets/DECISION_MEMORY_TEMPLATE.md docs/DECISION_MEMORY.md
   cp assets/AGENT_RULES_TEMPLATE.md .roo/rules-code/rules.md
   mkdir -p docs/sessions

3. Add your first decisions to docs/DECISION_MEMORY.md

Option 3: Claude Projects

Add SKILL.md to project knowledge + copy templates to project files.

Option 4: Manual / Other LLMs

Use the Decision Memory format and Session Log format manually.

For Cursor, Windsurf, or other AI tools, adapt AGENT_RULES_TEMPLATE.md to your tool's configuration format.

---

The 4 Components

1. Decision Memory

Architectural decisions as constraints. Agents read before implementing.

### [DEC-001] PostgreSQL Over MongoDB
**Category:** TECHNOLOGY  
**Date:** 2025-01-15  
**Status:** ACTIVE

**Context:** Need to choose primary database. Team has SQL experience.

**Decision:** Use PostgreSQL for all persistent data.

**Consequences:**
- All schemas use relational design patterns
- JSONB for semi-structured data where needed
- No document-style collections

Agent protocol:

• Read before significant changes
• Cite as [per DEC-XXX] when following
• STOP if action conflicts
• Propose new decisions for architectural choices

2. Confidence Protocol

Signal uncertainty at START of every response:

Level	Threshold	Behavior
🟢 CERTAIN	95%+	Proceed, log action
🔵 CONFIDENT	80-94%	Show intent, proceed
🟡 PROBABLE	60-79%	Explain rationale, request approval
🟠 UNCERTAIN	40-59%	Present options, human chooses
🔴 UNCLEAR	<40%	Ask first, don't proceed

Risk adjustments:

• DESTRUCTIVE: -15% | IRREVERSIBLE: -25% | SECURITY: -20%
• TESTED: +15% | REVERSIBLE: +10% | ISOLATED: +10%

3. STOP Triggers

Hard stops requiring human decision:

Category	Examples
Security	API keys, auth logic, encryption
Destructive	DELETE, DROP, bulk removal
Irreversible	Schema migrations, renaming
Financial	Payment code, pricing logic

When triggered: 🔴 UNCLEAR → Explain risk → Present options → Wait.

4. Session Logs

Per-task action tracing. One file per task.

# Session Log: SES-2025-12-29-001

**Date:** 2025-12-29
**Agent:** Claude Desktop

## Actions

| Action | Confidence | Decisions | Files |
|--------|------------|-----------|-------|
| Added loading spinner | 🟢 | [DEC-002] | dashboard.html |
| Fixed auth redirect | 🔵 | [DEC-003] | auth.py |

## Handoff
Next: implement caching per [DEC-004]

Rules:

• One file per task (never append)
• Sequential numbering: 001, 002, 003...
• Merge to *-recap.md daily
• For history: read only recap files

---

File Structure

project/
├── docs/
│   ├── DECISION_MEMORY.md          # Architectural constraints
│   └── sessions/
│       ├── SES-2025-12-29-001.md   # Task 1
│       ├── SES-2025-12-29-002.md   # Task 2
│       └── SES-2025-12-29-recap.md # Daily summary
├── .roo/rules-code/
│   └── rules.md                    # Agent rules (Roo Code)
└── CLAUDE.md                       # Project conventions

---

Multi-Agent Coordination

When multiple agents work on the same project, they share context via files:

File	Who Writes	Who Reads
docs/DECISION_MEMORY.md	Human + Agents	All agents
docs/sessions/SES-*.md	Each agent	All (recaps only)
CLAUDE.md / rules file	Human	All agents

Example workflow:

1. Claude Desktop analyzes: "Should we use MongoDB here?"
2. Finds [DEC-001] conflict, proposes options
3. Human decides, Claude Desktop logs session
4. Roo Code implements, reads same Decision Memory
5. Constraint maintained across both agents

---

Intended Scope

Designed for:

• Solopreneurs and indie developers
• Small teams (1-5 people)
• Startups in early stages
• Projects where one human can maintain full context

Not designed for:

• Enterprise teams (50+ engineers)
• Multi-team coordination
• Compliance-heavy environments

Why this boundary: Memory Trail optimizes for velocity and low overhead. The HITL model assumes a single human can verify claims and make decisions.

---

Prior Art

Memory Trail builds on established patterns. See PRIOR_ART.md.

Architecture Decision Records (ADRs): Nygard's original format, MADR
Project Memory: Cursor rules, CLAUDE.md conventions
Session Tracking: Development journals, captain's logs

The opportunity: ADRs exist but aren't optimized for AI consumption. Project memory files exist but lack decision tracking structure. Memory Trail bridges this gap.

---

Documentation

Document	Description
ARCHITECTURE.md	Full component specs, formats, protocols
PRIOR_ART.md	Landscape of related patterns
ROADMAP.md	Future development plans
SKILL.md	Claude skill implementation
assets/	Ready-to-use templates
examples/	Real-world usage examples

---

Related

Stream Coding Stack — Integrated methodology (Memory Trail + Stream Coding + Clarity Gate)
github.com/frmoretto/stream-coding-stack

Stream Coding — Documentation-first development methodology
github.com/frmoretto/stream-coding

Clarity Gate — Pre-ingestion verification for epistemic quality
github.com/frmoretto/clarity-gate

ArXiParse — Production system where Memory Trail was developed
arxiparse.org

---

License

CC BY 4.0 — Use freely with attribution.

---

Author

Francesco Marinoni Moretto

• GitHub: @frmoretto
• LinkedIn: francesco-moretto

---

Contributing

Looking for:

1. Integration — Cursor, Windsurf, other AI tool configurations
2. Templates — Domain-specific decision templates
3. Examples — Real project decision memories
4. Feedback — Is the 4-component structure right?

Open an issue or PR.