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.

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.

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.

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.

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.

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.

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.