Context Persistence

Copair persists session context at the project level so you can resume work across sessions without re-explaining what you were doing.

Project-Scoped Sessions

Sessions are stored in your project's .copair/sessions/ directory:

your-project/
  .copair/
    sessions/
      auth-middleware-refactor-a3f2/
        session.json        # Metadata
        messages.jsonl      # Raw conversation
        summary.md          # Generated summary
      fix-login-bug-b7c1/
        session.json
        messages.jsonl
        summary.md

Each session gets its own directory, scoped to the project. Running Copair in different projects writes to separate locations — no cross-instance conflicts.

If no project directory is detected, sessions fall back to ~/.copair/sessions/.

Auto-Derived Identifiers

Copair automatically names sessions based on what you're working on. The identifier is derived from:

  • Keywords from your first message
  • File paths touched during the session
  • The current git branch name

The format is <slug>-<short-hash>, e.g., auth-middleware-refactor-a3f2 or fix-login-bug-b7c1. This is generated after the first substantive exchange — empty sessions don't get named.

You can rename a session at any time:

> /session rename api-migration

Resuming Sessions

On Startup

When you launch Copair in a project with existing sessions, it presents a selection:

Previous sessions found:
  1. auth-middleware-refactor-a3f2  (2 hours ago, 15 messages, claude-4-sonnet)
  2. fix-login-bug-b7c1            (yesterday, 8 messages, gpt-4o)

Resume a session or start fresh? [1/2/n]

CLI Flags

Resume non-interactively:

copair --resume auth-middleware-refactor-a3f2    # Resume specific session
copair --resume latest                           # Resume most recent session

Session Summarization

When you exit a session (via /exit or Ctrl+C), Copair generates a summary capturing:

  • Task description and goals
  • Key decisions made
  • Files modified
  • Current state and next steps

The summary is stored alongside the raw messages in summary.md. On resume, the summary is injected as context instead of replaying the full message history — keeping the context compact and within the model's token limits.

Summarization Model

By default, summarization uses a local 7B model via Ollama (if available) to avoid API costs. If no local model is available, the active session model is used.

Configure the summarization model:

# .copair/config.yaml
context:
  summarization_model: ollama/llama4

Session Commands

Manage sessions with /session commands:

CommandDescription
/session listShow all sessions for the current project
/session resume [id]Resume a specific session
/session rename <name>Rename the current session
/session delete <id>Delete a stored session
/session saveForce a mid-session save/snapshot
/session infoShow current session details (identifier, message count, token usage)

Example

> /session list

Sessions for this project:
  ID                              Last Active    Messages  Model
  auth-middleware-refactor-a3f2    2 hours ago    15        claude-4-sonnet
  fix-login-bug-b7c1              yesterday      8         gpt-4o

> /session resume auth-middleware-refactor-a3f2

Resuming session: auth-middleware-refactor-a3f2
Loading summary context...
Ready. Last task: refactoring auth middleware to use JWT validation.

Multi-Instance Isolation

You can safely run multiple Copair instances in the same project. Each instance creates a separate session directory — no overwrites, no conflicts.

Session Retention

By default, Copair keeps only the most recent session per project. Configure retention:

# .copair/config.yaml
context:
  max_sessions: 5    # Keep up to 5 sessions

Cleanup runs at startup and after creating a new session.

Next Steps

Last updated May 12, 2026