Memory Ebbinghaus

Ebbinghaus forgetting curve-based memory lifecycle manager. Tracks memory items with strength decay, review reinforcement, and archiving.

Setup

First run — initialize the database:

python3 scripts/ebbinghaus.py status
# Auto-creates memory_db.json in current directory if not found

To use a custom path:

EBBINGHAUS_DB=/path/to/memory_db.json \
EBBINGHAUS_ARCHIVE=/path/to/MEMORY.md \
python3 scripts/ebbinghaus.py status

Environment variables:

Core Concept

Strength formula: strength = e^(-days_elapsed / stability)

Stability: starts at 1.0, multiplied by 1.5 on each review (the more you review, the slower it fades).

Commands

# View all memory items and their current strength
python3 scripts/ebbinghaus.py status

# Recalculate all strength values (run daily)
python3 scripts/ebbinghaus.py decay

# Add a new memory item
python3 scripts/ebbinghaus.py add "content description" --category <cat> --source <origin>

# Review and reinforce (resets strength to 1.0, stability ×1.5)
python3 scripts/ebbinghaus.py review <id>

# Delete a memory item
python3 scripts/ebbinghaus.py forget <id>

# Archive to MEMORY.md (removes from active list, appends to archive file)
python3 scripts/ebbinghaus.py archive <id>

# Heartbeat mode — print items needing attention
python3 scripts/ebbinghaus.py heartbeat

Heartbeat Integration

Add to your heartbeat config:

- Memory decay check: python3 /path/to/scripts/ebbinghaus.py heartbeat

Heartbeat output rules:

• 🔴 items exist → alert user, ask "review or forget?"
• Only 🟡 items → log silently, no interruption
• All 🟢 → output HEARTBEAT_OK

Categories

Typical Workflows

"Clean up old memories":

1. Run decay then status
2. List 🔴 items, ask user: review / forget / archive?
3. Execute chosen action

"Remember this: XXX":

1. Run add "XXX"
2. Confirm added

"Which memories are fading?":

1. Run decay to update strengths
2. Run status, highlight 🔴 items