Save a new memory.

Call this whenever you discover something important during a task (a fact, a preference, project status, an event). Self-score importance from 1-10 based on how significant it is in context. If a sufficiently similar existing memory is found (cosine similarity >= dup_threshold=0.95), it is reinforced as a duplicate and returned instead. You normally don't need to pass room (it's inferred automatically from the working directory). Only pass room="common" explicitly for universal memories that apply across every context.

Search for and return memories.

Always call this at the start of a task. It surfaces relevant past knowledge, preferences, and project context. mode="fast" searches only tier=hot, quickly. If the score is low it automatically falls back to deep. mode="deep" searches more broadly, including cold/superseded/episode memories, and follows associative links. mode="exhaustive" ignores activation and ranks purely by relevance across every memory. Use this as a last resort to dig up a "sunk" memory you're sure you recorded but that isn't surfacing under fast/deep. You normally don't need to pass room (it searches only the current room plus common). room="*" searches across all rooms — use it only when necessary, since it breaks the separation between work and personal contexts.

Report which memories actually turned out to be useful.

When a task finishes, report the ids of memories that actually helped. Reinforced memories are more likely to surface near the top on the next recall. Passing multiple ids at once links those memories together via a co-occurrence link (Hebbian learning). strength ranges 0.1-3.0 and controls how strong the reinforcement is.

Use this instead of forget when a memory turns out to be wrong.

Demotes the old memory to superseded (corrected) and creates a new memory that records the reason for the correction. Explicitly recording the mistake prevents the same error from being repeated (a hypercorrection effect).

Create an explicit link between two memories.

Call this when you want to manually connect related memories. Deep recall can then follow this link to surface memories associatively.

Soft-delete a memory (move it to trash).

Call this when a memory is no longer needed and you want it excluded from search. This moves the memory to trash rather than physically deleting it, so it can be restored if deleted by mistake. If you want to correct an error rather than remove a memory, use correct instead of forget.

Return clusters of episode memories that are candidates for consolidation.

Call this before ending a session (at session end), to surface clusters of similar older episodes that are candidates for compressing into knowledge or project memories. The LLM generates the summary, then calls mark_consolidated to complete the consolidation.

Record that a consolidation has been completed.

Call this after the LLM has summarized a cluster surfaced by consolidation_candidates and created the new memory via remember. The original episodes are demoted to cold (long-term storage) and linked to the new memory via a derived_from link. Also use this tool to demote the target episodes to cold after acting on a skill_candidates cluster.

Return clusters of episode memories that are candidates for extraction into a reusable skill.

When 3 or more (default; the "three-times rule") episodes recording the same shape of work (procedure) form a similar cluster, use this as input for judging whether that procedure is worth extracting into a reusable skill (a how-to document — a SKILL.md for Claude Code, etc.). Unlike consolidation_candidates, there is no age filter here (recently repeated work is exactly the target). Even when a cluster is found, always propose turning it into a skill to the user and get their approval first. Never create or deploy a skill on your own. Once the decision (adopt or pass) is made, record the reasoning via remember(type=knowledge), then clean up the original episodes with mark_consolidated(episode_ids, new_memory_id).

Rebuild the DB index from the Markdown files.

Call this after manually editing files, or when you suspect the DB is corrupted. Only memories that differ are re-embedded, so this is faster than a full rebuild.

Return memory statistics.

Shows memory counts (by type and tier), the number of access events, the number of links, and so on.