4.6 KiB

Raw Permalink Blame History

Agent Memory Management

Memory system with automatic decay, tiered search, and creative recall. Works with any directory of markdown files.

Quick Start

1. Scan existing files

python3 memory-engine.py scan <directory>

Reports: file count, YAML coverage, size, recommendations.

2. Bootstrap YAML frontmatter

python3 memory-engine.py init <directory> [--dry-run]

Adds relevance, last_accessed, tier to files missing frontmatter. Infers type from directory path. Infers dates from YAML fields, git log, or file mtime.

3. Run decay

python3 memory-engine.py decay <directory> [--dry-run]

Updates all cards: recalculates relevance scores and reassigns tiers. Schedule daily via cron for automatic forgetting.

4. Touch on read

python3 memory-engine.py touch <filepath>

Promotes card one tier up (graduated recall). Multiple reads = stronger memory.

5. Creative recall

python3 memory-engine.py creative <N> <directory>

Random sample from cold/archive tiers. Read these cards and look for unexpected connections.

6. Health check

python3 memory-engine.py stats <directory>

Shows tier distribution, context budget, stale card count.

Core Concepts

Three-Layer Architecture

Layer	What	Size Target	Loaded
Hot context	State file (volatile focus, blockers)	<4KB	Every turn
Searchable vault	Cards with YAML, one per entity	Unlimited	On demand
Archive	Old logs, completed work	Unlimited	Deep/creative only

Rule: Each fact lives in ONE place. If it's in a card, don't also put it in the state file. See docs/architecture.md for full design rationale.

Forgetting Curve

Cards have relevance: 0.0-1.0 that decays linearly over time:

Day 0: 1.0 (just accessed)
Day 7: 0.90 → tier: active
Day 21: 0.69 → tier: warm
Day 33: 0.50 → tier: cold
Day 60+: 0.10 (floor) → tier: archive

core tier is manual-only — for identity, security, pricing. Never auto-demoted.

Tier-Aware Search

Mode	Tiers searched	When
heartbeat	core + active	Quick checks, monitoring
normal	active + warm	Most questions
deep	all tiers	Strategy, complex analysis
creative	random cold+archive	Brainstorming, ideation

See docs/search-protocols.md for detailed protocols.

YAML Frontmatter

Minimum required fields (managed by engine):

---
relevance: 0.85
last_accessed: 2026-02-25
tier: active
---

See docs/yaml-schema.md for full schema with domain-specific fields.

Daily Files (Episodic Memory)

Daily files (YYYY-MM-DD.md) are the agent's episodic memory — what happened each day. They follow the same decay system as vault cards. Never delete them.

Lifecycle

Day 0:   Created (end of day cron or manual)     → tier: active, relevance: 1.0
Day 1-7: Auto-loaded at session start (today+yesterday) → tier: active
Day 8-21:  Searchable but not auto-loaded          → tier: warm
Day 22-60: Deep search only                        → tier: cold
Day 60+:   Creative mode or explicit recall         → tier: archive

Configuration

Generate default config:

python3 memory-engine.py config <directory>

Creates .memory-config.json:

{
  "tiers": {"active": 7, "warm": 21, "cold": 60},
  "decay_rate": 0.015,
  "relevance_floor": 0.1,
  "skip_patterns": ["_index.md"],
  "type_inference": {"crm/": "crm", "leads/": "lead"},
  "use_git_dates": true
}

Adjust tier thresholds and decay rate to match your domain's natural rhythm. Fast-moving domains (sales): tighter thresholds (active=3, warm=10, cold=30). Slow domains (research): wider thresholds (active=14, warm=45, cold=120).

Anti-Patterns

Don't	Do Instead
Load all contacts into state file	Keep them in vault cards, search on demand
Create "knowledge graph" that duplicates vault	Vault IS the graph. Use index files for navigation
Store same fact in 3 files	One card per entity, reference via links
Delete old daily files to "save space"	Keep all dailies, let tier decay handle visibility
Auto-load all daily files at session start	Load only today + yesterday; search older on demand
Search all 500 cards for every question	Check index first, filter by tier, then search
Touch every card during bulk operations	Only touch on meaningful read/update
Build elaborate review systems	Let decay handle it — if you don't use it, it fades

4.6 KiB Raw Permalink Blame History