Memory Layers

Cohaku organizes memories into three layers, each with different priority and lifecycle characteristics.

The Three Layers

Layer	Priority	Purpose	TTL
Rule	10 (highest)	Persistent instructions and constraints	None
Working	5	Current session context, temporary notes	Optional
Long-term	1	General knowledge, facts, patterns	None

Rules are the highest priority memories. They represent instructions, constraints, and preferences that should always be active.

"Always use TypeScript strict mode"
"Never commit directly to main"
"Use pnpm, not npm"

Rules are never expired and always included first in get_context results.

Working memories represent temporary, session-relevant context. They support optional TTL via expiresAt.

"Currently debugging the auth flow in src/auth.ts"
"The user prefers verbose error messages for this session"

Expired working memories are automatically excluded from get_context and listMemoriesByLayer.

Long-term memories store general knowledge accumulated over time.

"The project uses React 19 with TypeScript and Vite"
"The database schema was last migrated on 2026-01-15"

When get_context is called with a budget of N memories:

Budget: 50 memories
├── Rules: 5 (all rules included)
├── Working: ceil((50 - 5) * 0.6) = 27
└── Long-term: 50 - 5 - 27 = 18

When searching with search_memories, each memory receives a hybrid score:

score = semantic * 0.4 + bm25 * 0.3 + recency * 0.2 + salience * 0.1

Component	Description
Semantic	Cosine similarity from vector search (0-1)
BM25	Normalized full-text search rank (0-1)
Recency	Exponential decay from `lastAccessedAt` (half-life: 24h)
Salience	`importance` decayed over time

Weights are configurable per-query via the weights parameter.