elfmem: Instructions file for Claude Code

elf — Adaptive Memory for LLM Agents

elf (elfmem package) is a self-aware adaptive memory system. Agents learn, reinforce, and forget knowledge the way biological memory works — fast ingestion, deep consolidation at pauses, decay-based archival at rest. SQLite-backed. Zero infrastructure.

Core Mental Model

Four rhythms (every design decision maps to one of these):

• Heartbeat — learn(): milliseconds, no LLM, pure inbox insert
• Breathing — dream() / consolidate(): seconds, LLM-powered dedup + contradiction detection
• Sleep — curate(): minutes, decay archival + graph pruning + top-K reinforcement
• Deep Sleep — dream(rescore=True) / rescore(): re-evaluates aged active blocks against the current SELF; keeps alignment / summary / tags fresh as the agent's identity drifts (v0.13.3)

Four frames — always select before retrieving context: self · attention · task · simulate (simulate is the Theory-of-Mind frame: blends self constitution with mind/* blocks to reason about modelled minds.)

Knowledge lifecycle: BIRTH → GROWTH → MATURITY → DECAY → ARCHIVE Decay is session-aware (holidays don't kill knowledge). Reinforcement resets the clock.

Code Style

SIMPLE · ELEGANT · FLEXIBLE · ROBUST — full patterns in docs/coding_principles.md

• Functional Python — pure functions, input → output, compose pipelines from ≤50-line functions
• Fail fast — exceptions bubble up; catch only at CLI/MCP system boundaries
• No defensive code — no broad except, no try/except in business logic
• Complete type hints — every function, public and private
• Docstrings follow this template on every public method:

  USE WHEN: …   DON'T USE WHEN: …   COST: …   RETURNS: …   NEXT: …
  

• AgentGuide required: every new public MemorySystem method must have a corresponding AgentGuide entry in src/elfmem/guide.py GUIDES dict before the PR merges. This is what makes elfmem guide authoritative and keeps user project CLAUDE.mds permanently correct.