# 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):**

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

# Install Session Memory
pipx install session-memory
```

**Linux / virtualenv:**

```bash
pip install session-memory
```

**Windows:**

```powershell
# Install with pip
pip install session-memory

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

**Verify:**

```bash
session-memory --version
```

### 2. Configure Your AI Clients

Run once on your machine:

```bash
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:

```bash
cd ~/projects/my-project
```

Then run:

```bash
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:

```bash
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

```bash
session-memory install
```

Configure supported AI clients on this machine.

```bash
session-memory init
```

Enable Session Memory instructions for the current repository.

```bash
session-memory doctor
```

Verify installation and configuration.

```bash
session-memory status
```

Show current project/session status.

```bash
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:

```bash
session-memory doctor
```

For more help see:

- [docs/INSTALL.md](docs/INSTALL.md)
- [docs/TROUBLESHOOTING.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