agent-session

One session. Any coding agent. Switch between Claude Code, Codex, OpenCode — and whatever ships next — without re-explaining the work.

Agent Session is not another AI memory database. It is a local, Git-aware session layer: agents are interchangeable workers, and the session is the portable state of the work. One binary, one SQLite file per project, no daemon.

Features

• Local-first, zero-config — single binary + SQLite. No PostgreSQL, Redis, Docker, Node or Python.

• Agent-agnostic — shared state over transcripts: task, decisions, progress, files, tests, blockers, next action. Adapters for Claude Code, Codex, OpenCode, Cursor, Cline, pi, omp (oh-my-pi).

• Git-aware — git is the source of truth for code; the session stores only state and context.

• MCP-native — 26 tools + 7 resources over stdio or streamable-http.

• Human-readable — .agent/context/current.md and deterministic handoff context, never locked in a proprietary DB.

• Checkpoint & handoff — snapshot the work, hand it to another agent deterministically.

• Always available — agents spawn the stdio MCP server on demand; optional user-scope registration.

• Long-term memory — knowledge store with SQLite FTS5 full-text search; auto-extracts decisions, resolved blockers and completed tasks from sessions (non-LLM).

• Agent Plugin packaging — ships as a portable plugin (agent-plugins.org v1.0.0).

Related MCP server: myc

Install

Prebuilt binaries for macOS, Linux and Windows (amd64 + arm64) are published on every release. Pick whichever path is easiest for you.

macOS & Linux

Homebrew (recommended on macOS):

brew install anaknegeri/tap/agent-session

One-line curl installer (installs both agent-session + agent-session-mcp, auto-detects the latest version):

curl -fsSL https://raw.githubusercontent.com/anaknegeri/agent-session/main/scripts/install.sh | sh

Options: AS_VERSION=0.1.2 to pin a version, AS_INSTALL_DIR=~/.local/bin to install without sudo.

Windows

PowerShell (installs to %LOCALAPPDATA%\agent-session and adds it to your PATH):

irm https://raw.githubusercontent.com/anaknegeri/agent-session/main/scripts/install.ps1 | iex

Any platform with Go

go install github.com/anaknegeri/agent-session@latest

From a release

Grab the matching asset from the latest release (agent-session-{os}-{arch}, Windows uses .exe), then:

chmod +x agent-session-* && sudo mv agent-session-* /usr/local/bin/

Update

brew upgrade agent-session        # Homebrew installs
agent-session update              # binary / curl installs (auto-checks GitHub releases)

From source

Requires only Go binary + Git:

make build             # bin/agent-session + bin/agent-session-mcp
make install           # copies to ~/.local/bin
make cross-compile     # dist/ for all 6 platform/arch combos

Global availability in Claude Code

Register at user scope so agent-session appears in claude mcp list from every directory:

agent-session plugin install claude --scope user

Quick start

cd your-project
agent-session init                # one command: init + wire agents at user scope
agent-session start "Implement OAuth2 PKCE"
agent-session status              # progress, blocked, next
agent-session checkpoint --next-action "Fix refresh token rotation"
agent-session handoff codex       # deterministic context for the next agent
agent-session resume --agent opencode
agent-session history             # event log
agent-session context             # print context.md

agent-session init is the one-command entrypoint per project, modeled after git init: it initializes the project (creates .agent/, starts a session) and wires AGENTS.md plus all agents. It is idempotent — safe to re-run. agent-session setup is an alias. Add --no-agents for the session layer only, or --only claude|opencode|codex to wire a single agent.

Not a git repo yet? init reminds you to run git init first. The session works in local-only mode meanwhile, but Agent Session is Git-aware and tracks branch/commit/diff once git exists.

CLI reference

Make every agent use Agent Session automatically

One command per project — it initializes if needed and wires the agent-session MCP server once at user scope, so your project stays clean:

cd your-project
agent-session init

What init does (idempotent, safe to re-run):

• .agent/ — project session state (required, per-project by design).

• AGENTS.md — appends a mandatory workflow section read by OpenCode, Codex, Cursor and Claude Code: agents first call session.get + context.get, track work with task.* / decision.* / blocker.* / event.append, and create a checkpoint before finishing.

• User-scope MCP registration (only for agents installed on this machine, no per-project config files created):

  • Claude Code — claude mcp add --scope user agent-session

  • OpenCode — ~/.config/opencode/opencode.json

  • Codex — codex mcp add agent-session (global by default)

  • Cursor — ~/.cursor/mcp.json

  • Cline — no user scope; wire per-project with --only cline

  • pi — ~/.pi/agent/ extension + skill + prompts. pi ships no MCP ("No MCP. Build CLI tools with READMEs, or build an extension that adds MCP support"), so it is wired through the CLI instead: an extension resumes and checkpoints on pi's own lifecycle events, and a skill teaches the model the task / decision / blocker / event verbs. Nothing MCP is registered.

  • omp (oh-my-pi) — ~/.omp/agent/mcp.json + extension + skill + slash commands. omp is a pi derivative that does ship an MCP client, so it gets both halves: the MCP server for tool calls, and an extension that resumes on session_start and checkpoints on session_before_compact / session_shutdown so continuity does not depend on the model remembering. Note the roots — omp reads .omp/ and ~/.omp/agent/, never .pi/, so pi's wiring does nothing here. Named profiles (omp --profile x) read ~/.omp/profiles/x/agent/ and are not covered by user-scope wiring.

The MCP server resolves the project root from the working directory, so the same user-scope registration works in every project, with no per-project config pollution.

init also installs slash commands at user scope (Claude Code ~/.claude/commands/, OpenCode ~/.config/opencode/commands/, Cursor ~/.cursor/commands/, pi ~/.pi/agent/prompts/, omp ~/.omp/agent/commands/) so you can run /agent-session, /agent-session-checkpoint, and /agent-session-record in any project. plugin uninstall <agent> --scope user removes them. pi gets its own wording of the three: the shared set tells the agent to call MCP tools, which pi has none of — omp uses the shared set, because it has.

Prefer per-project wiring? Use agent-session init --project, or --only <agent> to wire a single agent into this project only. --no-agents keeps the session layer only.

MCP

"Does the MCP server need to be running?"

No. With stdio (the default used by the adapters), Claude Code / OpenCode / Codex spawn the server automatically as a subprocess on demand and shut it down when the session ends. There is no daemon to manage.

With streamable-http the server is a persistent daemon. Auto-start templates:

• macOS: packaging/launchd/com.agent-session.mcp.plist.tmpl

• Linux: packaging/systemd/agent-session-mcp.service.tmpl

The daemon picks a unique per-project port (hash of the project root in 45100–47099, with free-port fallback):

agent-session mcp --transport streamable-http        # e.g. http://127.0.0.1:46688/mcp
agent-session-mcp --transport streamable-http --addr auto

In a project that is not yet initialized, the server stays connected and tools return project not initialized, run agent-session init instead of a connection failure.

Tools

session.get, session.checkpoint, session.diff, session.resume, session.record, context.get, context.read, context.update, context.summarize, task.create, task.get, task.update, decision.list, decision.create, blocker.create, blocker.list, blocker.resolve, event.append, workspace.status, workspace.diff, memory.put, memory.get, memory.search, memory.delete, memory.promote

session.record is the unified way to log work — it appends an event, records a decision, sets next_action, and/or creates a checkpoint in a single call.

Resources

session://current, session://context, session://decisions, session://tasks, session://workspace, session://checkpoint/latest, memory://recent

Canonical events

session.started, task.created, task.updated, file.changed, command.executed, test.started, test.failed, test.passed, decision.created, blocker.created, checkpoint.created, handoff.created, session.completed

Large event payloads (>8KB) are stored as artifacts and referenced by artifact_id.

Long-term memory (Phase 4)

Memory is separate from session state. The knowledge table is a long-term store with SQLite FTS5 (porter tokenizer) full-text search:

• Kinds — project_knowledge, architecture, solution, preference, skill

• Manual — memory.put by the agent or agent-session memory put

• Auto-promote (non-LLM) — memory.promote extracts structured session state: decision → architecture, resolved blocker → project_knowledge, completed task → solution. Idempotent — already-promoted entities are skipped.

Token savings

Agent Session is designed to keep prompts small (state over transcript):

• Progressive context loading — context.get defaults to a bounded summary, not full history.

• Context budget — configurable limits ([context]): max decisions/blockers/ files/events/progress, per-item truncation, and a hard total clamp (max_total_chars). Lists render as … +N more.

• Relevant memory injection — context.get automatically surfaces top-k related knowledge (local FTS search of the current task) so agents don't re-derive known facts.

• Tool annotations — MCP tools carry readOnlyHint / destructiveHint / idempotentHint where they hold, so agents pick the right tool without trial-and-error. Tools that create a record carry none: a repeat call creates a second one.

• PreCompact checkpoint — Claude Code saves a checkpoint before context compaction, so nothing is lost when the window shrinks.

• Agent-driven summarizer — context.summarize asks the agent itself to write a short session summary and store it via memory.put (kind project_knowledge). No external LLM API needed.

• Artifacts — large event payloads are stored as references, not inline.

Tune in .agent/config.toml:

[context]
max_decisions  = 5
max_blockers   = 3
max_files      = 8
max_events     = 10
max_progress   = 10
max_item_chars = 200
max_total_chars = 4000
inject_memory  = true
max_memory     = 3

# How many checkpoints of each kind a session keeps. Limits are per kind so a
# burst of automatic checkpoints cannot evict the deliberate ones. 0 = unlimited.
[retention]
max_manual     = 50
max_auto       = 20
max_precompact = 10
max_handoff    = 20

Every checkpoint records what triggered it — manual, auto (Stop hook or a stale context), precompact, or handoff — and retention is applied per kind. The session's most recent checkpoint is never pruned.

Benchmark

Reproducible benchmark at bench/token-benchmark.sh measures the real output size (in characters) of context-gathering operations, converted to approximate token cost (chars ÷ 4). Token estimates use the standard English-text heuristic; your model's exact tokenizer may differ.

Methodology — "Without" = manual exploration an agent must do on every cold start / post-compaction / handoff (read README, AGENTS.md, git log, git status, git diff, glob source files). "With" = a single context.get call.

Results (live run on this repo, 2026-08-12)

Cumulative savings over multiple re-orientations

Context depth comparison

The three depths select different content, so recent is not simply summary plus more — which is why it can measure slightly smaller:

• summary — bounded lists, the max_total_chars clamp, and nudges.

• recent — the same list bounds, no total clamp, no nudges, plus a recent-events section.

• full — no bounds at all, plus recent events.

Which one is larger therefore depends on whether the session's nudges outweigh its event list, and both can vary per repository and per session.

"Without agent-session" is a minimum — in practice agents also search code, read specific files, and re-derive decisions that agent-session preserves structurally. Real-world savings are higher.

Reproduce:

./bench/token-benchmark.sh

Project discovery

The MCP server is registered once at user scope, so it can start in a directory that has nothing to do with the project being worked on. The project root is resolved in this order:

1. $AGENT_SESSION_PROJECT, when it names a directory that exists

2. the nearest ancestor containing .agent/, searching no further up than the git repository that contains the starting directory

3. the git repository root, when there is no .agent/ inside it yet

4. the starting directory

The search stops at the repository boundary on purpose. Running agent-session init in $HOME once puts a .agent/ above every repository, and without that boundary any uninitialized repo underneath resolved to that unrelated project and recorded its session there. Outside a git repository there is no boundary to stop at, which is what AGENT_SESSION_PROJECT is for:

AGENT_SESSION_PROJECT=/path/to/project agent-session context

Automatic recording & nudges

Agent Session is designed so agents never have to remember to record state:

• Auto-record file changes — context.get compares git status against recorded events and appends file.changed for anything new, so file edits are captured even if the agent never calls event.append.

• Auto-checkpoint when stale — if no checkpoint exists in the last 10 minutes and the git tree is dirty, context.get creates one automatically.

• Context nudges — the summary view warns about stale checkpoints (>30 min), unrecorded changed files, and open blockers, so the agent knows when to checkpoint.

• session.record — record an event, a decision, next_action, and/or a checkpoint in one tool call instead of several.

Configuration

.agent/config.toml — zero-config defaults, human-editable:

[project]
name = "sakreta"

[storage]
driver = "sqlite"

[session]
auto_checkpoint = true      # checkpoint after task/decision/test events
smart_checkpoint = true     # rate-limit auto-checkpoints (max 1 per 60s)

[git]
enabled = true

[agents.claude]
enabled = true

[agents.codex]
enabled = true

[agents.opencode]
enabled = true

[sync]
mode = "local-only"         # local-only | git-sync | cloud-sync (phase 2)

Local data layout

project/
└── .agent/
    ├── config.toml           # configuration
    ├── session.db            # SQLite: projects, sessions, tasks, decisions,
    │                         #   blockers, session_events, checkpoints,
    │                         #   agent_sessions, artifacts, knowledge (+FTS)
    └── context/
        └── current.md        # human-readable current state (re-generated)

Everything stays local. Add .agent/ to .gitignore, or commit it later for git-sync (phase 2).

config.toml records the format version ([format] version = 1) so a future build can tell whether it understands the layout — see docs/spec/format-v1.md.

Security & privacy

• Local only by default — no data leaves the machine.

• A shared session is untrusted context. Any agent can write to it, so everything an agent authored — task titles, decisions, blockers, event payloads, memory — is rendered under an (untrusted) heading with a legend saying it is data and not instructions, and is flattened to a single line first so it cannot forge a section of its own. The MCP server states the same rule in its initialization instructions.

• No credentials or secrets are stored by the session layer.

Contracts

A session is written by one agent and read by another, often by a different build of this binary. Seven interfaces cross that boundary and are specified in docs/spec, all at v1:

The versions live in pkg/contract and every one of them is held to its spec by test/contract, so drift fails the build instead of surfacing later as an agent misreading a session. .agent/, each checkpoint and each export document record the version they were written against, and a build refuses to read a version it does not understand rather than guess.

The rule: bump for any change that could make an existing reader wrong, no bump for additive change. See docs/spec/README.md.

Development

make build     # build both binaries
make test      # go test ./...
make vet       # go vet ./...
make plugin    # package the Agent Plugin

Layout: clean architecture (Domain → Application → Infrastructure) with Wire DI. See ARCHITECTURE.md for the full schema, MCP design and development order.

Testing: SQLite :memory: unit tests, real-git integration fixtures, in-process MCP client tests, real MCP-over-stdio integration tests, and a live end-to-end flow (init → task → checkpoint → handoff → resume). Real-agent smoke tests (Claude Code / Codex / OpenCode) run with AGENT_SESSION_SMOKE=1 where the agent CLIs are installed. See test/integration/COMPATIBILITY.md for the agent capability matrix.

License

MIT — see LICENSE.