sessions: persistent memory and a task list for Claude Code and AI agents

Project memory for AI agents that survives /clear, /compact and new sessions

Every Claude Code session starts from zero, and parallel agents do not know about each other. sessions keeps a project's "session books" in a database instead of markdown files in the repo: the handoff from the last session, a pending ledger of open tasks, a chronicle of what was done, standing invariants (rules and do-not-touch areas) and long documents. An agent reads all of it in one call at the start of a session and writes back in one call at the end.

Several worktrees, machines and agents write to the same books at once without conflicts, because the database arbitrates, not git. It started as memory for coding agents and works just as well as a daily task list (see Daily tasks).

Session handoff, task ledger and shared books

• Pickup and handoff

  session_pickup returns the latest handoff, the open tasks, recent history and the project rules in one read; session_handoff records the end of a session in one transaction.

• Pending ledger with advisory claims

  Open tasks with priorities; an agent claims an item so others see it is in hand (advisory, never a lock).

• Chronicle

  Append-only history of what was done, searchable across projects (session_search).

• Invariants

  Standing rules the next agent must respect: do-not-touch areas, environment quirks, policies, kill switches.

• Documents and pictures

  Plans, designs and decision records attached to tasks; screenshots attached to records.

• Deploy leases

  Advisory notes of who is deploying what to which target.

• Many agents at once

  Several worktrees, machines and parallel agents on one project; each write reports what the others changed since you last read.

• Cross-project groups

  An owner groups projects so their agents read each other's books and file requests and documents into each other's task lists.

• Code index (optional, off by default)

  The owner switches it on; the project's default branch is indexed and searchable by text and, optionally, by meaning (embeddings), kept fresh automatically. Needs the project's git repository address and a read-only GitHub deploy key added by the repository admin.

• Skills served by the server

  The client keeps only small stubs; every slash command comes in its current version from the server (see Skills).

• Isolation and security

  One token = one project; tokens are stored only as sha256 and are revocable instantly; a deleted project sits in a 7-day quarantine and can be restored.

MCP tools

The server exposes eight tools:

• session_pickup
• session_note
• session_handoff
• session_read
• session_search
• session_knowledge
• session_project
• session_skill

How to connect an HTTP MCP server with a bearer token in Claude Code

Four steps. The token is project-scoped and is shown only once.

1. Sign in to the abt.nz cabinet, open the Sessions tab, create a project by name (1-64 characters: lower-case letters, digits, _ and -, starting with a letter or digit; names need not be unique) and issue a project token. The token is shown ONCE. A git repository address is optional and can be added later; it is needed only for the code index.

2. In the repository (or the folder you work from), register the server privately. Local scope means the token is never committed:

   claude mcp add --transport http --scope local sessions https://sessions.abt.nz/mcp \
       --header "Authorization: Bearer <token>"

3. Once per machine, ask the agent: install the sessions skills. It shows the stubs and writes them after you confirm.

4. Start every session with /pickup, end it with /handoff (see Skills).

Other MCP clients

Any client that speaks streamable HTTP with a bearer header works. Do not commit the token: keep this file out of version control.

{"mcpServers": {"sessions": {"type": "http", "url": "https://sessions.abt.nz/mcp", "headers": {"Authorization": "Bearer <token>"}}}}

Claude Code skills and the working cycle: pickup, askme, orchestrate, handoff

The skills are slash commands served by the server. They form one loop, and every step is cheap to repeat:

1. /pickup - start of every session. One read of the books; the agent tells you where you left off, what is live, what is pending, what not to touch, and the first step. Cheap to repeat after a compaction.
2. /askme [task] - settle a task BEFORE any work starts. The agent restates the task in plain words, then asks questions one at a time (a recommended option first, never a question the code or the books already answer), and records the outcome once: a decisions document linked to the task's card. Writes no code.
3. /orchestrate <task> - agent orchestration: the agent becomes an orchestrator and carries the task through the project's own discipline: plan, implementation by sub-agents, review, checks, PR, merge and deploy, with the project-specific steps taken from the project's rules (.claude/orchestrate.md or a "## Orchestrate" section in CLAUDE.md). Typed as the first word of a message.
4. /handoff - end of the session. One transaction: a short pointer for the next session (what to do first), chronicle entries for what was done, tasks opened, closed or reworded, rules recorded, documents filed.
5. /clear or /compact - Claude Code's own commands to reset or compress the context. Nothing is lost: the books hold the state, and the next /pickup restores the picture in one call.

More skills

• /ledger-loop - work through the open tasks on your own, oldest first: check each is still current, claim it, build it, open a PR and stop at green checks; never merges; hard caps per run.
• /sweep <area> - cleanup with a coverage map: scan one area for dead code, duplication and stale tests and report; removal only on a separate, confirmed run.
• /knowledge-onboard - switch the code index on and hand the read-only deploy key to the repository owner.

Install once per machine: ask the agent install the sessions skills; it shows the stubs and writes them after you confirm.

Not only code: an AI task manager and daily to-do list with Claude

sessions is not tied to coding. The same books work as a personal or team daily task list driven by an AI agent:

• Ledger = to-do list: tasks with priorities (CRITICAL, HIGH, MEDIUM, LOW ...), claimed when in hand, closed with a resolution; long-lived items stay open on purpose.
• Chronicle = diary of what was done and when, searchable.
• Documents = notes: plans, decisions, meeting notes, research, attached to the task they belong to.
• Invariants = standing rules: things to always respect or never touch.
• Daily rhythm: morning /pickup gives the agenda (yesterday's handoff, open tasks by priority); /askme turns a vague task into a settled one; the day's work is recorded as it goes; evening /handoff leaves tomorrow's first step.
• Everywhere: the same list from any machine where the agent runs; several people's projects can be grouped so they file tasks into each other's lists.

Examples

Planning a week, tracking a hiring pipeline, running a small business's to-dos, research with notes per topic, household admin.

A project is created by name; a git repository is optional and can be added later (for example github.com/you/repo). It is needed only for the code index. A non-code task list, research or documents need no repository at all.

What sessions costs

Free until payment is enabled. Charges start once payment is enabled on abt.nz; until then sessions is free.

• Free

  Up to 300 MB per project (books + code index + vectors).

• 60 RUB per GB

  Above 300 MB: 60 RUB per started GB per month, charged daily from the owner's abt.nz wallet; quota and rounding are per project.

• If unpaid

  Unpaid for 3 days: only the projects above the free 300 MB become read-only until payment; reads always work; data is never deleted; free projects keep working.

Limits

• Up to 10 own projects, 20 active tokens and 20 groups per user.
• Rate limit on /mcp for cabinet tokens: 120 requests per minute, burst 30, per token; a user's tokens together get twice that.

Frequently asked questions