Skip to content
Documentation

Remember & reuse

Session state

Record progress, inspect caches and resume retained context.

Status by featureReviewed September 2026

Inspect the current state

{"name":"ctx_session","arguments":{"action":"status"}}

Confirm the project and current task before resuming. Retained files and findings can become stale when the source changes.

Each agent resumes its own session

From LeanCTX 3.11.5, session continuity belongs to one agent. The wake-up briefing, session findings in search results and every other session read or write use only the calling agent’s own session, or what an explicit handoff brought into it. They never use the project’s latest saved session, which may belong to another agent.

A new agent therefore starts with project knowledge only. Project knowledge stays shared across agents. To pick up your own work after a restart, load your session by its id:

{"name":"ctx_session","arguments":{"action":"load","session_id":"<id>"}}

Without a session_id, load uses your own session, never the project’s latest one.

To pass work to another agent on purpose, create a handoff instead of relying on a shared session.

Record the next useful step

{"name":"ctx_session","arguments":{"action":"task","value":"Verify the authentication middleware against the current route configuration"}}

Keep progress concrete. Recording “complete” does not run tests or certify that another agent delivered its work.

Current session versus saved snapshots

The CLI uses session for live state and sessions for the saved store. Inspect snapshots before restoring or deleting them.

Checkpoints, read caches and the context ledger each have their own actions and retention semantics. A cache reset is not a host-conversation reset.

Compact a supported proxy conversation

The current source contract adds ctx_session actions compact and restore. This is an advanced proxy path: the MCP server records a directive, and a supported proxy applies it to subsequent model requests. The reviewed implementation targets Anthropic-style messages and declines histories containing OpenAI-style tool roles. It does not rewrite an arbitrary AI client’s conversation.

For compact, supply your summary in value. Preserve decisions, constraints, file paths and unresolved work. keep_recent_turns defaults to six recent user turns and is bounded to a minimum of four. The proxy respects protected cache prefixes and tool-pair boundaries when selecting the eligible span.

On this registered MCP path, restore clears the compaction directive. Original history can return on the next request only if the client still sends that history. This differs from restoring saved session snapshots. The reviewed directive has a 30-minute lifetime and a five-minute interval between new compactions. See the exact session contract and proxy boundary; do not infer support from a CLI version number alone.

What continuity does not include

LeanCTX does not automatically own every message in an external AI tool. Its briefing contains retained context that the integration actually supplies.

SDK workspace and handoff records use their own versioned transfer contract. They preserve selected state and provenance; they do not transfer a running process or expand recipient permissions.

Sources & versions5 references Reviewed
Core checkout
0ce2207ee4
Reviewed runtime
3.10.2
SDK release
1.1.0

Separate baselines for source, CLI/configuration and SDK contracts. Review does not certify every platform or integration.

Versions & compatibility