| name | memory |
| description | Read and update persistent memory. Use when: user says 'remember', asks about past context, preferences, or projects. Also use proactively to save anything reusable before a conversation ends. |
Memory System
Memory is stored as fragments in a SQLite database, indexed with BM25 + vector embeddings.
Mining runs frequently and recent.md is refreshed from fragments. Garbage collection is manual only; decay is a review signal, not a deletion policy.
Lookup — always search first
term-llm memory search "<query>" --agent "$AGENT_NAME" --limit 6
Hybrid BM25 + vector search — use it for anything that might be in memory. Search is relevance-only by default; use --freshness/--recency only when newer matching facts should win. Use --touch only when you explicitly want to record access metadata.
Show full fragment by numeric ID (preferred — no truncation):
term-llm memory fragments show 42 --agent "$AGENT_NAME"
List and filter:
term-llm memory fragments list --agent "$AGENT_NAME" --limit 10
term-llm memory fragments list --agent "$AGENT_NAME" --filter-path telegram
Writing new memory
Use the CLI to add or update fragments directly in the database:
term-llm memory fragments add fragments/<category>/<name>.md --agent "$AGENT_NAME" --content "..."
term-llm memory fragments update fragments/<category>/<name>.md --agent "$AGENT_NAME" --content "..."
Delete only when the user explicitly asks or when replacing a provably wrong fragment:
term-llm memory fragments delete fragments/<category>/<name>.md --agent "$AGENT_NAME"
Category guide:
preferences/ — stable user and agent behavior preferencespeople/ — user/family/profile factshomelab/ — infrastructure, services, network, runbooksprojects/ — long-lived project context, decisions, scarsskills/ — skill-specific operating notestools/ — external tools, APIs, tool behaviorsnippets/ — reusable commands/workflowsnotes/ — unclassified knowledge; promote periodically into better roomsbugs/ — open bugs or memorable scarsfeedback/ — user corrections; fold into preferences/personality over timecredentials/ — credential locations and handling rules only; never raw secretsindex/ — maps and palace navigation
Memory palace
Use memory/palace.md as the compact map of durable context that should be visible every session. Keep it tiny and room-like:
## Shape rules
- Prefer `fragments/<room>/<shelf>/<topic>.md`.
- Avoid per-session/per-PR/per-update fragments unless they are active work.
- Store credential locations, not raw secrets.
## User / preferences
- Stable preferences, collaboration style, durable constraints.
## People
- User/family/profile facts.
## Projects
- Long-lived project facts and decisions.
## Homelab / infrastructure
- Repos, services, commands, credential locations (never secrets).
## Tools / skills
- Tool behavior and skill operating notes.
## Open loops
- Durable unresolved work only; remove resolved loops during consolidation.
Do not dump transcripts into the palace. Promote durable facts into fragments first, then consolidate the current-state summary.
Consolidation
Preview consolidation first:
term-llm memory consolidate --agent "$AGENT_NAME"
Apply only when the preview is good:
term-llm memory consolidate --agent "$AGENT_NAME" --apply
memory consolidate is current-state consolidation: it rewrites recent.md from changed fragments and prints a non-destructive decay preview. It does not perform full palace cleanup, delete fragments, move fragments, or rewrite stored decay scores.
For full palace cleanup, work room-by-room: back up source rows, create/update a canonical fragment, then explicitly delete superseded source fragments only after verifying search still finds the canonical memory.
Backup convention before deleting many fragments:
mkdir -p /home/agent/artifacts/memory-consolidation/$(date +%F)
Recommended cadence:
- Mine sessions frequently (for example every 30 min).
- Run
memory consolidate --apply daily to keep recent.md tidy.
- Run deep palace cleanup manually or as a weekly dry-run/report; apply only with explicit judgment.
When user says "remember this"
- Add the fragment immediately via CLI
- If the fact is stable and globally useful, keep the palace/recent summary in mind for the next consolidation
- Confirm to user
Memory rules
- Search before answering anything about user preferences, history, or projects
recent.md is loaded at session start and maintained from fragments — do not hand-edit it casually- Prefer updating source fragments, then consolidating
- The session miner handles most things automatically after conversations end
- Proactively create fragments when content is structured or unlikely to survive miner summarisation
Job schedule (created by bootstrap-jobs)
| Job | Schedule | Purpose |
|---|
mine-sessions | every 30 min | Extract fragments from transcripts |
update-recent | every 10 min | Promote fragments into recent.md |
