Handoff

Close out the current session and produce its hand-off brief. Call this at the END of a session, or when the user signals they're stopping or switching context. It finalises the session note and returns the brief the next session will read.

Compress old finished sessions into durable entity notes ('sleep'). Call this when a project's session log has grown large and you want to reclaim space while keeping the lasting knowledge: it distils old sessions into the durable entity notes and archives the originals. Requires a configured LLM (HANDOFF_LLM_MODEL); it is the only step that uses one.

Load the prioritised hand-off brief for a project. Call this at the START of a session, before doing anything else, to learn where the previous session left off: the goal, the next step, key decisions and their rationale, dead-ends already ruled out, and open questions. Retracted decisions are omitted. This is a curated brief, not a raw context dump.

Record a progress signal for the current work session. Call this proactively as work happens — every time you set or change the goal, make a non-trivial decision (and why), hit a dead-end worth not repeating, touch an important file, surface an open question, or decide the next step. Keep each event ATOMIC and concise: one item per call, 1-2 sentences. Log several small events rather than dumping a whole session summary into one — the brief is meant to stay skimmable. Reference durable notes inline as [[Entity]] so they link in the brief's "Related knowledge". This is how the next session inherits your context. Returns the new event id (use it later in `supersedes`). If `supersedes_query` retired a prior event, a second line names which id was retired (or notes that none matched), so the retraction is auditable.

Record durable, long-lived project knowledge on an entity note. Use this (rather than log_event) for facts that outlive a single session: the system's architecture, coding conventions, what a component does, or standing open questions. These notes are linked from sessions via [[wiki-links]] and form the project's knowledge graph. Returns the entity name.

Search memory across sessions and projects. Call this whenever the user references past work, a prior decision, or ANOTHER project — e.g. "in one of my projects we did X", "how did we solve Y before", "what did we decide about Z", "last time". Use scope='all' (the default) to recall across every project; scope='current' to stay in this one. Returns matching past events with their project, content, and id — the id can be fed straight into log_event's `supersedes` to retire a decision you just found to be outdated.

Sync this device's memory vault with its private git remote. Use when the user wants their memory on another device, or to push/pull now. If the vault isn't configured yet, this returns setup instructions — relay them and ask the user for a private repo URL, then call again with remote_url. Once configured, a bare call pulls remote work, commits local changes, and pushes. Safe to call repeatedly.