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:

bash

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

To use a custom path:

bash

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

Environment variables:

VariableDefaultDescriptionEBBINGHAUS_DB``./memory_db.jsonPath to the JSON databaseEBBINGHAUS_ARCHIVE``./MEMORY.mdFile to append archived memories

Core Concept#

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

StatusStrengthMeaning🟢 Active≥ 0.7Recently used, clear memory🟡 Decaying0.3–0.7Not used for a while🔴 Fading< 0.3Needs review or cleanup

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

Commands#

bash

# 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:

text

- 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#

categoryMeaningprojectProject/task completiontechTechnical findings/solutionspersonMemory about someoneeventImportant eventsgeneralOther

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