memory

Memory

Persistent cross-session memory for rafayels-engineering, implemented as Case-Based Reasoning (CBR) with local vector retrieval. Inspired by Memento — agents stay frozen, improvement comes through retrieval of past cases, not by editing prompts.

Quick Start

# One-time setup
python3 ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/memory.py init

# Verify everything works
python3 ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/memory.py doctor

# Write a case
python3 ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/memory.py write \
  --phase plan \
  --query "How to structure marketplace sync" \
  --plan "Use rsync -a --delete for mirroring" \
  --outcome "Clean one-way sync, idempotent" \
  --tags '["marketplace","sync"]'

# Retrieve relevant past cases for a phase
python3 ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/memory.py query \
  "setting up marketplace sync" --phase plan --k 3

# Add a signal (success, failure, review outcome, etc.)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/memory.py signal \
  42 merge 1.0 --source "pr:#123"

When This Skill Activates

This skill is model-invocable. It should auto-activate when:

• The user asks to "remember" something
• The user asks "what did we do before for X?"
• The user asks to "recall" prior decisions or patterns
• Running /workflows:brainstorm, /workflows:plan, /workflows:work, /workflows:review, /workflows:compound — these have explicit retrieve and capture hooks
• Running /re:memory-review for audit

Architecture

┌─────────────────────────────────┐
│  memory CLI (one-shot)          │
│  18 subcommands, --json on all  │
└─────────────────────────────────┘
         │
         ├─(vector ops)─> embedder.py ─> embed_daemon.py (Unix socket)
         │                                  fallback: in-process fastembed
         │
         └─(storage)──> db.py ─> sqlite-vec @ ~/.claude/plugins/
                                 rafayels-engineering/memory.db

Key Design Decisions

• Frozen agents: never edits agent or skill files. All improvement flows through retrieval. Pattern-detection PRs are generated by the separate memory-proposer skill with human review required.
• Quarantine-on-write: new cases require 2+ positive signals before becoming retrievable. Defends against case bank poisoning.
• MMR reranking: top-10 candidates → MMR rerank to K=3 for diversity.
• Exponential reward decay: reward * exp(-age_days/60) at retrieval time.
• PARTITION KEY on phase: sqlite-vec vec0 pre-filters by phase before distance calculation. Single biggest performance win.
• cases_raw + cases_vec split: source of truth stays in plain SQL table, vec0 is an index. Enables model upgrades without reinference.
• Offline-first: fastembed + sqlite-vec, no cloud API calls. Graceful degradation if deps missing.

CLI Reference

Create

Command	Description
memory init	Create DB and schema
memory write --phase P --query Q ...	Write a new case (starts quarantined)
memory seed --source docs/solutions/	Bootstrap from existing solution docs
memory import FILE	Import cases from JSONL export

Read

Command	Description
memory query "text" --phase P --k 3	Semantic retrieve with MMR
memory read <case_id>	Fetch a single case by ID
memory list [--phase] [--status] [--limit]	Filter cases by metadata
memory report --stats	Aggregate statistics
memory report --stale --older-than 90	Find prune candidates
memory doctor	Self-diagnose readiness
memory export [--output FILE]	Export all cases + signals as JSONL

Update

Command	Description
memory signal <id> <type> <value>	Append a signal (types: merge, ci, approval, review, regression)
memory update <id> [--title] [--tags] [--outcome]	Update case metadata
memory promote <id>	Pin a case as promoted (never auto-archived)
memory link <id_a> <id_b>	Mark two cases as related

Delete

Command	Description
memory prune [--reward-below 0.3] [--older-than 90] [--confirm]	Archive low-value cases (dry-run by default)
memory delete <id> --confirm-token <token>	Hard-delete a case (requires two-step confirmation)
memory daemon-stop	Stop the embedder daemon

All commands accept --json for machine-readable output.

Exit Codes

Code	Meaning
0	Success
1	Not found
2	Validation error
3	Storage error
75	Memory unavailable (EX_TEMPFAIL — dependencies missing, workflows should tolerate)

Setup

pip install -r ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/requirements.txt
python3 ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/memory.py init
python3 ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/memory.py doctor

First invocation downloads the BGE-small model (~67MB) into ~/.cache/rafayels-memory/fastembed/. Subsequent runs use the cached model.

Reference Files

• schema.md — Database schema reference
• signals.md — Signal types, weights, and reward formula
• injection-guide.md — How workflows hook into memory
• case-format.md — Case structure and injection budget

Related

• memory-proposer skill — Pattern detection and auto-PR generation
• /re:memory-review command — Interactive audit workflow
• compound-docs skill — Documents solved problems (paired with memory seed)

Troubleshooting

macOS: AttributeError: 'sqlite3.Connection' object has no attribute 'enable_load_extension'

Cause: macOS system Python and pyenv-installed Python are built without the loadable SQLite extension API. sqlite-vec cannot load into these interpreters.

Fix: Use Homebrew Python 3.12 which ships with --enable-loadable-sqlite-extensions:

brew install python@3.12
/opt/homebrew/bin/python3.12 -m pip install --break-system-packages \
  -r ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/requirements.txt

Then invoke memory.py with Homebrew Python explicitly:

/opt/homebrew/bin/python3.12 ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/memory.py <subcommand>

Alternative: rebuild pyenv Python with extension support:

PYTHON_CONFIGURE_OPTS="--enable-loadable-sqlite-extensions" pyenv install 3.12.12

This is a macOS-specific platform limitation, not a memory layer bug. Linux distros typically ship Python with extension support enabled.

Python version compatibility

The memory layer requires Python 3.10–3.12. Python 3.13+ is not currently supported because fastembed==0.4.2 doesn't publish wheels for those versions. Pin yourself to 3.12 for now.

CLI flag ordering

The --json flag is a top-level argparse option, so it must come before the subcommand:

# ✅ Correct
memory --json write --phase plan --query "..."

# ❌ Fails with "unrecognized arguments: --json"
memory write --phase plan --query "..." --json

memory doctor reports unavailable

Install dependencies:

pip install -r ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/requirements.txt

Workflows skip memory injection silently Check memory doctor --json. If status is degraded or unavailable, the workflows are correctly degrading. Install missing deps to re-enable.

Queries return empty results The cold-start threshold requires k*3 active cases per phase. Write more cases (via normal workflow use) or run memory seed to bootstrap.

Daemon won't start

python3 ${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/memory.py daemon-stop
# Delete stale PID file if needed
rm -f /tmp/rafayels-memory-$(id -u)/embed.pid
# Next query will auto-spawn a fresh daemon

Cross-project learning not working The DB is user-scope at ~/.claude/plugins/rafayels-engineering/memory.db — shared across all projects. Verify the path with memory doctor --json.