Three Tier Memory

Three-Tier Memory System

The three memory files that give AI persistent context across sessions. Each tier has a different scope, update frequency, and purpose.

---

Why three tiers?

A single memory file doesn't work:

• Too granular → bloated, hard to scan
• Too coarse → misses important details
• Same update frequency for everything → either stale or noisy

Three tiers separate concerns by time horizon and stability:

graph TD
    subgraph "Long-term Memory"
        PM[project-memory.md<br/>Architecture, constraints<br/>Update: rarely]
    end
    subgraph "Mid-term Memory"
        DL[decisions-log.md<br/>ADRs, trade-off reasoning<br/>Update: on architecture changes]
    end
    subgraph "Short-term Memory"
        TH[task-history.md<br/>Last 30 task summaries<br/>Update: every task]
    end
    PM -->|Informs| DL
    DL -->|Informs| TH
    TH -->|Accumulates into| DL
    DL -->|Stabilizes into| PM

Loading

---

Tier 1: Long-term — project-memory.md

File: .github/agent/memory/project-memory.md

Purpose: Stable facts about the project that change rarely.

Contents:

• Project name, type, business scenario
• Tech stack (language, framework, database, test framework)
• Architecture diagram and module list
• Design principles
• Key constraints (hard rules that must not be violated)
• Known issues and common pitfalls
• Development environment setup

Update frequency: Rarely — when the project fundamentally changes (new module, tech stack change, new constraint).

Example entry:

## ⚠️ Key Constraints

1. Never push to git without explicit user request
2. All API endpoints must have input validation
3. Database migrations must be reversible
4. Test coverage must stay above 80%

Size guideline: Keep under 500 lines. Rotate old facts to ADRs in decisions-log.md if the file grows too large.

---

Tier 2: Mid-term — decisions-log.md

File: .github/agent/memory/decisions-log.md

Purpose: Record of technical decisions with their context and rationale. Uses the ADR (Architecture Decision Record) format.

Contents:

• Decision title and date
• Status (Accepted / Deprecated / Superseded)
• Background (why this decision was needed)
• Options compared (with pros/cons table)
• Decision and rationale
• Impact (what this affects)

Update frequency: When an architecture or technology decision is made.

Example entry:

### ADR-003: Use SQLite FTS5 for full-text search

- **Date**: 2026-06-15
- **Status**: ✅ Accepted

#### Background
Need product search. Considered Elasticsearch, PostgreSQL full-text, and SQLite FTS5.

#### Options

| Option | Pros | Cons |
|--------|------|------|
| Elasticsearch | Powerful, scalable | Heavy dependency, operational cost |
| PostgreSQL FTS | Already have PG | Migrating from PG to SQLite |
| SQLite FTS5 | Zero-dependency, fast enough | Less powerful than ES |

#### Decision
SQLite FTS5.

#### Rationale
Single-user app, <100K products. FTS5 handles this easily without adding a service dependency.

#### Impact
Search queries go through FTS5 virtual table. No new infrastructure needed.

---

Tier 3: Short-term — task-history.md

File: .github/agent/memory/task-history.md

Purpose: Running log of recent tasks. Provides immediate context for the next session.

Contents:

• Task ID and title
• Date
• Type (feat / fix / refactor / chore)
• Summary of what was done
• Files changed
• Notes for future sessions

Update frequency: Every task. This is the non-negotiable Act phase output.

Example entry:

### [TASK-013] Add product search endpoint

- **Date**: 2026-06-15
- **Type**: feat
- **Summary**: Added GET /api/products/search?q=... using SQLite FTS5. Returns paginated results with relevance scores. Added input validation for empty/missing query parameter.
- **Files changed**: api/products.py (+45), tests/test_products.py (+30), models/product.py (+12)
- **Notes**: FTS5 index is created in models/product.py. Search is case-insensitive by default. Pagination uses cursor-based approach (see ADR-003).

Retention policy: Keep the last 30 entries. Archive older entries to docs/task-history-archive-YYYY-QN.md.

---

How the tiers work together

Session 1:  Install ai-coding-ok
            → project-memory: tech stack, architecture
            → decisions-log: ADR-001 (SQLite choice)
            → task-history: TASK-001 (install)

Session 5:  Add search feature
            → AI reads all 3 files, knows about SQLite FTS5 decision
            → task-history: TASK-005 (search feature)

Session 20: Refactor database layer
            → AI reads all 3 files, sees 20 tasks of context
            → decisions-log: ADR-004 (new DB pattern)
            → task-history: TASK-020 (refactor)

Session 50: New team member joins
            → AI reads all 3 files, has 50 entries of history
            → Can explain: "We use SQLite because ADR-001. We refactored DB in TASK-020."

---

Comparison: hand-written AGENTS.md vs ai-coding-ok memory

	Hand-written AGENTS.md	ai-coding-ok memory
Initial setup	Manual placeholders to fill	One-sentence question, AI infers the rest
Mid-term decisions	Lost (or in scattered PRs)	Captured as ADRs in decisions-log.md
Recent task context	Lost between sessions	Last 30 tasks in task-history.md
Memory update	Manual (and often forgotten)	Automated via PDCA Act phase
State after 10 iterations	Stale snapshot	Living record with 10 entries

---

Memory files size budget

File	Recommended max	Why
project-memory.md	500 lines	Beyond this, AI skims instead of reading
decisions-log.md	50 ADRs	Archive deprecated ADRs to a separate file
task-history.md	30 entries	Older entries → docs/task-history-archive-YYYY-QN.md

All three files combined are typically <10KB — negligible in the AI's context window.

---

Next steps

• PDCA Workflow — how memory is read and written in the PDCA loop
• Four Modes — when Mode B reads memory, when Mode C writes it
• Daily Workflow — practical memory usage day-to-day