---
id: 550e8400-e29b-41d4-a716-446655440000
title: "Human-readable title"
type: semantic
created: 2026-01-23T10:30:00Z
---

# Title

Content here.

{uuid}-{slug}.memory.md

---
# REQUIRED (always include these 4)
id: 550e8400-e29b-41d4-a716-446655440000
title: "Human-readable title"
type: semantic
created: 2026-01-23T10:30:00Z

# COMMON (add when useful)
modified: 2026-01-23T14:22:00Z
namespace: _semantic/decisions/project
tags:
  - architecture
  - database

# === PROGRESSIVE DISCLOSURE ===
summary: "PostgreSQL chosen for ACID compliance and JSON support"
detail_level: comprehensive  # minimal | standard | comprehensive
related_memories: []  # UUIDs of related memories
supersedes: []  # UUIDs of memories this one replaces

# === BI-TEMPORAL TRACKING ===
temporal:
  valid_from: 2026-01-23T00:00:00Z    # When fact became true
  valid_until: null                    # When fact expired (null = current)
  recorded_at: 2026-01-23T10:30:00Z   # When captured in system
  ttl: P90D                            # ISO 8601 duration until expiry
  decay:
    model: exponential                 # Decay algorithm
    half_life: P7D                     # Time to 50% relevance
    strength: 0.85                     # Current relevance score 0-1
  access_count: 5                      # Times recalled
  last_accessed: 2026-01-23T14:22:00Z # Last recall timestamp

# === PROVENANCE ===
provenance:
  source_type: conversation            # user_explicit | inferred | conversation
  source_ref: file:///path/to/source.ts:42
  agent: claude-opus-4                 # Capturing agent
  confidence: 0.95                     # Certainty score 0-1
  session_id: abc123                   # Claude session ID

# === CODE STRUCTURE AWARENESS ===
code_refs:
  - file: src/auth/handler.ts
    line: 42
    symbol: authenticateUser
    type: function                     # function | class | method | variable | type

# === CITATIONS ===
citations:
  - type: documentation                # paper | documentation | blog | github | stackoverflow | article
    title: "Source Title"
    url: https://example.com/source
    author: "Author Name"              # optional
    date: 2026-01-23                   # publication date, optional
    accessed: 2026-01-23T10:30:00Z     # when accessed, optional
    relevance: 0.90                    # how relevant to memory 0.0-1.0, optional
    note: "Brief description"          # optional context

# === CONFLICT TRACKING ===
conflicts:
  - memory_id: xyz789
    resolution: merged                 # merged | invalidated | skipped
    resolved_at: 2026-01-23T12:00:00Z

# === COMPRESSION (Auto-generated) ===
summary: "Concise 2-3 sentence summary (max 500 chars)"  # Auto-generated by gc --compress
compressed_at: 2026-01-24T10:00:00Z                      # When compression occurred
---

# Memory Title

Main content in markdown format.

## Section 1

Detailed information...

## Rationale

Why this decision/pattern/learning matters.

## Relationships

- relates-to [[other-memory-id]]
- supersedes [[old-memory-id]]
- derived-from [[source-memory-id]]

## Entities

- mentions @[[PostgreSQL]]
- uses @[[JWT Authentication]]

---
id: abc123
type: semantic
namespace: _semantic/knowledge/project
title: "REST API Authentication Endpoint"
tags:
  - api
  - authentication
---

# REST API Authentication Endpoint

POST /api/v1/auth/login

## Request
- email: string (required)
- password: string (required)

## Response
- token: JWT access token
- expires_in: seconds until expiry

---
id: def456
type: episodic
namespace: _episodic/sessions/blockers/project
title: "Database connection timeout incident"
tags:
  - incident
  - database
  - resolved
temporal:
  valid_from: 2026-01-20T14:30:00Z
  recorded_at: 2026-01-20T16:00:00Z
---

# Database Connection Timeout Incident

## What Happened
On 2026-01-20 at 14:30 UTC, production database connections started timing out.

## Root Cause
Connection pool exhaustion due to unclosed connections in the batch processor.

## Resolution
Added connection.close() in finally block. Deployed fix at 15:45 UTC.

## Prevention
- Added connection pool monitoring
- Set max connection lifetime to 5 minutes

---
id: ghi789
type: procedural
namespace: _procedural/patterns/project
title: "Database migration procedure"
tags:
  - database
  - deployment
  - procedure
---

# Database Migration Procedure

## Prerequisites
- Database backup completed
- Maintenance window scheduled
- Rollback script prepared

## Steps

1. Enable maintenance mode
   ```bash
   ./scripts/maintenance.sh enable

npm run db:rollback

---

## Namespace Reference

| Namespace | Purpose | Memory Type |
|-----------|---------|-------------|
| `_semantic/decisions/` | Architectural choices, rationale | semantic |
| `_semantic/knowledge/` | APIs, context, learnings, security | semantic |
| `_semantic/entities/` | Entity definitions (technologies, components) | semantic |
| `_episodic/incidents/` | Production issues, postmortems | episodic |
| `_episodic/sessions/` | Debug sessions, work sessions | episodic |
| `_episodic/blockers/` | Impediments, issues | episodic |
| `_procedural/runbooks/` | Operational procedures | procedural |
| `_procedural/patterns/` | Code conventions, testing strategies | procedural |
| `_procedural/migrations/` | Migration steps, upgrade procedures | procedural |

### Memory Scope

- **Project**: `{org}/{project}/{namespace}/` - Specific to current codebase
- **Organization**: `{org}/{namespace}/` - Shared across projects in org

---

## Progressive Disclosure Structure

Every comprehensive memory should include three disclosure levels in the body:

### Level 1: Quick Answer (Default Recall)

The `## Quick Answer` section provides a 1-3 sentence summary. This is what Claude returns first when recalling a memory.

**Triggers for Level 1:** "What is X?", "Which X do we use?", basic recall

### Level 2: Context (Expanded Recall)

The `## Context` section provides:
- Decision date/timeframe
- Alternatives considered
- Key decision drivers
- Trade-offs made

**Triggers for Level 2:** "Why?", "Tell me more", "Explain the reasoning"

### Level 3: Comprehensive (Full Detail)

The `## Full Detail` section includes:
- Complete alternatives analysis
- Implementation notes
- Related decisions/patterns
- Code references
- Citations

**Triggers for Level 3:** "All details", "Full context", implementation work, debugging

### Progressive Disclosure Template

```markdown
# {Title}

## Quick Answer
{1-3 sentence summary answering "what" and "why briefly"}

## Context
- **Decision date:** {date}
- **Alternatives considered:** {list}
- **Key drivers:** {factors that led to decision}
- **Trade-offs:** {what was sacrificed}

## Full Detail

### Alternatives Analysis
1. **{Option 1}**: {pros/cons, why rejected or chosen}
2. **{Option 2}**: {pros/cons, why rejected or chosen}

### Implementation Notes
- {Specific implementation details}
- {Configuration requirements}
- {File locations}

### Related Decisions
- See: [[{related-memory-id}]] for {context}

### Code References
- {file:line} - {description}

### Citations
- {source title} - {url}

## Relationships

- relates-to [[550e8400-e29b-41d4-a716-446655440000]]
- supersedes [[old-memory-id]]
- derived-from [[source-memory-id]]
- contradicts [[conflicting-memory-id]]
- implements [[design-memory-id]]

## Entities

- mentions @[[PostgreSQL]]
- uses @[[JWT Authentication]]
- authored-by @[[John Smith]]
- located-in @[[src/auth/]]

# Generate compliant filename
UUID=$(uuidgen | tr '[:upper:]' '[:lower:]')
TITLE="My Memory Title"
SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | head -c 50)
FILENAME="${UUID}-${SLUG}.memory.md"

---
id: {uuid}
type: semantic
namespace: _semantic/knowledge/project
created: {timestamp}
title: "{title}"
summary: "{Brief summary for quick recall}"
detail_level: minimal
---

# {Title}

## Quick Answer
{Content - serves as both summary and full content for minimal memories}

---
id: {uuid}
type: semantic
namespace: _semantic/decisions/project
created: {timestamp}
title: "Decision: {what}"
tags:
  - architecture
summary: "{Brief 1-sentence summary of decision and key reason}"
detail_level: comprehensive
related_memories: []
supersedes: []
provenance:
  confidence: 0.95
---

# Decision: {What}

## Quick Answer
{What} was chosen for {primary reason}. This enables {key benefit}.

## Context
- **Decision date:** {date}
- **Alternatives considered:** {Option A}, {Option B}, {Option C}
- **Key drivers:**
  - {Driver 1}
  - {Driver 2}
- **Trade-offs:** {What was sacrificed for this choice}

## Full Detail

### Alternatives Analysis
1. **{Option A}**: {Description}
   - Pros: {pros}
   - Cons: {cons}
   - Verdict: {Chosen/Rejected because...}

2. **{Option B}**: {Description}
   - Pros: {pros}
   - Cons: {cons}
   - Verdict: {Rejected because...}

### Implementation Notes
- {Specific implementation details}
- {Configuration requirements}

### Related Decisions
- relates-to [[{related-decision-id}]]

## Relationships
- supersedes [[{old-decision-id}]] (if applicable)

---
id: {uuid}
type: episodic
namespace: _episodic/sessions/blockers/project
created: {timestamp}
title: "Incident: {summary}"
tags:
  - incident
temporal:
  valid_from: {when_it_happened}
---

# Incident: {Summary}

## Timeline
- {time}: {event}

## Root Cause
{Why it happened}

## Resolution
{How it was fixed}

## Prevention
{How to prevent recurrence}

---
id: {uuid}
type: semantic
namespace: _semantic/knowledge/project
created: {timestamp}
title: "Learning: {topic}"
tags:
  - research
citations:
  - type: paper
    title: "Research Paper Title"
    url: https://arxiv.org/abs/...
    author: "Smith et al."
    date: 2025-11-15
    accessed: {timestamp}
    relevance: 0.95
    note: "Key finding about X"
  - type: documentation
    title: "Official Documentation"
    url: https://docs.example.com/...
    accessed: {timestamp}
    relevance: 0.85
---

# Learning: {Topic}

## Summary
{What you learned}

## Key Points
- {Point 1 from citation 1}
- {Point 2 from citation 2}

## Application
{How this applies to our project}