Memory Crystals
Why crystals exist#
After months of active use, your Brain can accumulate thousands of lessons. Sending all of them into every AI session bloats the context window and buries the signal. Crystallization distills thousands of lessons into a few dozen high-signal patterns, one per category, that fit comfortably in every briefing.
| Without crystals | With crystals |
|---|---|
| Raw lesson list grows unbounded → context bloat → signal dilution | Dense category-grouped digest → clean briefing → AI acts on proven wisdom |
How it works#
- Accumulate lessons. As you work, cachly stores every fix, revert, and architecture decision in your Brain through git hooks and session learning.
- Crystallize. Call
memory_crystalize()(or schedule it monthly). cachly reads all lessons, groups them by category — deploy, fix, debug, arch, perf — and compresses them into a structured digest. - Recall at session start.
session_startautomatically includes your latest crystal in every AI briefing. The AI arrives with compressed wisdom, not raw noise. - Inspect with
crystal_view. Shows top patterns per category, lesson count, age, and optionally the raw JSON crystal data.
Tools#
memory_crystalize#
Creates or refreshes the crystal. Reads all lessons from your Brain, groups them by category, compresses into a crystal, and stores it at cachly:crystal:latest. Returns a digest of what was crystallized.
# Optional: label this crystal
memory_crystalize(label="Q1 2026")
# Without a label — auto-generated from date
memory_crystalize()
Run it monthly, or after any major project milestone.
crystal_view#
Inspect the current crystal — top patterns per category, total lesson count, crystal age, and when it was last refreshed.
crystal_view()
# Full JSON for debugging
crystal_view(show_raw=true)
Crystal categories#
| Category | Covers |
|---|---|
deploy |
Deployment patterns, env issues, rollback triggers |
fix |
Recurring bugs, their root causes, and validated solutions |
debug |
Debugging workflows, tool chains, log locations |
arch |
Design decisions, trade-offs, rejected approaches |
perf |
Bottlenecks found, optimizations applied, benchmarks |
Recommended schedule#
Run memory_crystalize at the end of each month or after completing a major project phase. New lessons always accumulate in the live Brain — crystallization compresses them into the briefing digest without discarding anything from the graph.
If you haven't crystallized yet, session_start falls back to the raw lesson list, capped at 20 recent items. After your first crystal, the briefing switches to crystal mode automatically.
Related#
Crystals sit downstream of the 3-Layer AI Memory System — set memory up first, then crystallize once lessons start accumulating. See MCP Integration for how session_start pulls the crystal into every briefing automatically.