Session Memory

Persistent local memory for AI coding sessions.

Start work in Windsurf. Continue later in Cursor, Codex, or Claude without manually explaining what happened in the previous conversation.

Session Memory stores your project context locally on your machine and gives supported AI agents the information they need to continue where another session stopped.

Why Session Memory?

AI conversations normally lose context when you:

• start a new chat
• switch from Windsurf to Codex
• switch from Cursor to Claude
• restart your IDE
• return to a project later

Session Memory solves this by keeping important project state outside the AI conversation.

A fresh AI session can retrieve:

• what you are building
• current implementation state
• important decisions
• files changed
• tests and results
• bugs
• open TODOs
• blockers
• next recommended action

How It Works

AI Session A
    ↓
important work recorded
    ↓
Session Memory
    ↓
local storage
    ↓
AI Session B
    ↓
get_context()
    ↓
continue where Session A stopped

Session Memory uses four main concepts:

• Events — important things that happened.
• Checkpoints — the current save point of the work.
• Memories — important knowledge or decisions that should survive across sessions.
• Context — the compact information a new AI needs to continue.

Privacy

Session Memory is local-first.

Your memory is stored on your machine under:

~/.session-memory/

It is not automatically shared with teammates.

Each engineer using Session Memory has their own independent local memory.

Requirements

• Python 3.10+
• macOS, Linux, or Windows
• A supported AI client such as Windsurf, Cursor, Codex, or Claude

Quick Start

1. Install Session Memory

macOS (recommended):

# Install pipx if you don't have it
brew install pipx
pipx ensurepath

# Install Session Memory
pipx install session-memory

Linux / virtualenv:

pip install session-memory

Windows:

# Install with pip
pip install session-memory

# If not in PATH, add Python Scripts directory to your PATH
# Then restart your terminal

Verify:

session-memory --version

2. Configure Your AI Clients

Run once on your machine:

session-memory install

Session Memory detects supported clients and configures them automatically.

For example:

Session Memory Setup

✓ Windsurf detected
✓ Cursor detected
✓ Codex detected

✓ Session Memory MCP configured

You should not normally need to manually edit MCP configuration files.

3. Initialize a Repository

Go to a project where you want persistent AI context:

cd ~/projects/my-project

Then run:

session-memory init

This configures repository-level AI instructions such as AGENTS.md.

It does not place your session history inside the repository.

Your actual memory remains under:

~/.session-memory/

4. Verify Everything

Run:

session-memory doctor

Example:

Session Memory Doctor

✓ Runtime
✓ MCP server
✓ Local storage
✓ Windsurf configured
✓ Cursor configured
✓ Project initialized

READY

5. Work Normally

Open Windsurf, Cursor, Codex, or another configured client.

You do not need to say:

• "Start Session Memory."
• "Save this conversation."
• "Load my old memory."

Just work normally.

For example:

Continue implementing authentication.

The agent automatically uses Session Memory to:

start/resume session
        ↓
load previous context
        ↓
continue work
        ↓
record important events
        ↓
checkpoint progress

Example

Day 1 — Windsurf

You say:

Implement OAuth login.

During the session the agent records:

Decision:
Use PKCE.

File:
src/auth/service.py

Test:
17 passed, 2 failed.

Bug:
Refresh-token expiry handling fails.

TODO:
Fix token rotation.

Day 2 — Codex

Open the same repository and start a fresh Codex conversation.

Say:

Continue working on this project.

Codex retrieves:

Goal:
Implement OAuth login

Current State:
OAuth login works.
Refresh-token rotation is incomplete.

Decision:
Use PKCE.

Important File:
src/auth/service.py

Known Bug:
Refresh-token expiry handling fails.

Tests:
17 passed, 2 failed.

Open Task:
Fix token rotation.

Next Action:
Fix refresh-token expiry handling.

You do not need to explain yesterday's conversation.

Where Is the Data Stored?

Session Memory stores data locally:

~/.session-memory/
└── projects/
    └── <project-id>/
        ├── project.json
        ├── CURRENT.md
        ├── memories/
        └── sessions/
            └── <session-id>/
                ├── session.json
                ├── events.jsonl
                ├── checkpoints/
                └── artifacts/

Your source repository only needs the small AI instruction file such as:

AGENTS.md

Session history itself is not committed to the repository.

Main Commands

session-memory install

Configure supported AI clients on this machine.

session-memory init

Enable Session Memory instructions for the current repository.

session-memory doctor

Verify installation and configuration.

session-memory status

Show current project/session status.

session-memory uninstall

Remove Session Memory configuration from AI clients without deleting your memory by default.

MCP Workflow

Agents normally use these tools automatically:

• start_session
• get_context
• append_event
• checkpoint_session
• resolve_todo
• search_history
• search_memory
• end_session

Users normally do not need to call these manually.

What Gets Recorded?

Session Memory focuses on information useful for future continuation:

• important decisions
• significant file changes
• commands and test results
• bugs and errors
• TODOs
• blockers
• discoveries
• checkpoints

It does not attempt to store hidden model reasoning.

Agent-Assisted Capture

Session Memory does not magically observe everything happening inside an AI client.

The configured AI agent calls Session Memory tools when important work occurs.

Repository instructions such as AGENTS.md guide supported agents to do this automatically.

Cross-AI Continuity

The intended workflow is:

Windsurf
    ↓
Session Memory
    ↓
Codex
    ↓
Session Memory
    ↓
Cursor
    ↓
Session Memory
    ↓
Claude

All clients on the same machine can use the same local project memory.

Local-Only Team Usage

Multiple engineers can install Session Memory.

Each engineer gets their own independent storage:

Engineer A
→ ~/.session-memory/

Engineer B
→ ~/.session-memory/

Their session data is not automatically exchanged.

Troubleshooting

Run:

session-memory doctor

For more help see:

• docs/INSTALL.md
• docs/TROUBLESHOOTING.md

Important Principle

Session Memory is not a transcript database.

Its goal is simple:

A fresh AI should understand enough of the previous work to continue correctly without the user re-explaining the project.

License

MIT