Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Session Memory what was I working on in this project?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
Related MCP server: ai-cortex
AI Session A
↓
important work recorded
↓
Session Memory
↓
local storage
↓
AI Session B
↓
get_context()
↓
continue where Session A stoppedSession 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.
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.
Python 3.10+
macOS, Linux, or Windows
A supported AI client such as Windsurf, Cursor, Codex, or Claude
macOS (recommended):
# Install pipx if you don't have it
brew install pipx
pipx ensurepath
# Install Session Memory
pipx install session-memoryLinux / virtualenv:
pip install session-memoryWindows:
# Install with pip
pip install session-memory
# If not in PATH, add Python Scripts directory to your PATH
# Then restart your terminalVerify:
session-memory --versionRun once on your machine:
session-memory installSession Memory detects supported clients and configures them automatically.
For example:
Session Memory Setup
✓ Windsurf detected
✓ Cursor detected
✓ Codex detected
✓ Session Memory MCP configuredYou should not normally need to manually edit MCP configuration files.
Go to a project where you want persistent AI context:
cd ~/projects/my-projectThen run:
session-memory initThis 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/Run:
session-memory doctorExample:
Session Memory Doctor
✓ Runtime
✓ MCP server
✓ Local storage
✓ Windsurf configured
✓ Cursor configured
✓ Project initialized
READYOpen 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 progressYou 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.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.
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.mdSession history itself is not committed to the repository.
session-memory installConfigure supported AI clients on this machine.
session-memory initEnable Session Memory instructions for the current repository.
session-memory doctorVerify installation and configuration.
session-memory statusShow current project/session status.
session-memory uninstallRemove Session Memory configuration from AI clients without deleting your memory by default.
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.
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.
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.
The intended workflow is:
Windsurf
↓
Session Memory
↓
Codex
↓
Session Memory
↓
Cursor
↓
Session Memory
↓
ClaudeAll clients on the same machine can use the same local project memory.
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.
Run:
session-memory doctorFor more help see:
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.
MIT
Record an important event that future AI sessions may need. Use during work for meaningful decisions, bugs, test results, TODOs, discoveries, commands, or state changes. Use user_message to capture meaningful facts, requirements, preferences, constraints, or context the user provides — the user should NOT need to say 'remember this' or 'save this'. Proactively record useful user-provided information. Do NOT record trivial conversation (hello, thanks, okay) or private chain-of-thought.
Inputs: content (required), event_type (required), actor, metadata, +2 more.
Create a recovery snapshot of the current work state. Call after meaningful milestones, before ending work, or before switching to another major task. Include enough state (goal, current_state, next_action) that a fresh AI could continue from this point without needing the full conversation history.
Inputs: goal, session_id, next_action, current_state, +1 more.
Finalize the current work session. Call after recording unfinished TODOs and creating a final checkpoint. Previously recorded events are already durable; this operation finalizes the session for clean handoff to the next AI.
Inputs: session_id, final_overview, workspace_path.
Get information about the currently active session.
Inputs: workspace_path.
Retrieve continuation context from previous sessions for the current project. Call this IMMEDIATELY after start_session and BEFORE making significant changes. Use the returned goal, current state, decisions, bugs, TODOs, files changed, and next recommended action to continue previous work correctly. This is the most important tool for cross-session continuity. NOTE: This returns selective/compact context. If specific information is not found here, use search_memory() for durable facts or search_history() for detailed historical events.
Inputs: project_id, current_task, workspace_path, include_recent_sessions.
Retrieve a session by ID with its events and checkpoint.
Inputs: session_id (required).
List recent sessions.
Inputs: limit, workspace_path.
Record an important activity during work. Use for: decisions (architecture/implementation choices), bugs (issues discovered), todos (unfinished work), commands (significant commands run), test_result (test outcomes), error (errors encountered). Record outcomes, not reasoning. Be specific: 'Use PKCE for OAuth' not 'Made a decision'.
Inputs: category (required), description (required), metadata, workspace_path.
Record a significant file change after the change is actually made. Include the path, what changed, and why. Do not log every temporary edit. Example: 'src/auth.py modified - Added refresh token validation before issuing new access token.'
Inputs: path (required), change_type (required), description, lines_added, +2 more.
Recover an abandoned or crashed session.
Inputs: session_id (required).
Store a long-term memory with provenance. Memories persist across sessions and can be retrieved later.
Inputs: content (required), project_id (required), memory_type (required), tags, +2 more.
Mark a previously recorded TODO as resolved after the work has been completed. Use this when an open task from get_context has been finished. Resolved TODOs remain in history but no longer appear under Open Tasks.
Inputs: todo_text (required), resolution, todo_event_id.
Search exact historical session events when current context does not contain enough detail. Use for questions about previous commands, errors, file changes, test results, bugs, user-provided information, or historical actions. Returns raw events from past sessions. Call this when get_context() and search_memory() do not contain the needed information. Different from search_memory which searches curated long-term knowledge.
Inputs: query (required), limit, event_types, session_ids, +1 more.
Search durable project knowledge and previous important decisions. Use when reasoning depends on why a previous architectural or implementation decision was made, or to find long-term project facts, conventions, and user preferences. Call this when get_context() does not contain the needed information.
Inputs: query (required), project_id (required), limit, memory_types.
Start or resume Session Memory tracking for the current project. Call this AUTOMATICALLY at the beginning of meaningful project work (e.g., 'Continue implementing auth', 'Fix the tests', 'Work on the API'). After starting, immediately call get_context to load previous project state. Do NOT start sessions for trivial questions like 'What does this function do?'
Inputs: workspace_path (required), goal, title, force_new.
Update an existing memory's content or status.
Inputs: memory_id (required), status, content, importance.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 16 tools
append_event and log_activity are near-duplicates, both recording important events/activities with overlapping examples like decisions, bugs, TODOs, and test results; remember also blurs into append_event's territory. The retrieval tools are well-differentiated, but these boundary issues create real misselection risk.
Nearly every tool follows a clean snake_case verb_noun pattern such as start_session, search_memory, and list_sessions. The single-verb 'remember' is the main deviation, and append_event/log_activity are synonymous in style, but the overall convention is consistent.
16 tools is at the heavy end for a session-memory server, especially with redundant event-recording tools like append_event and log_activity. Each cluster has a purpose, but consolidating the overlapping logging tools would make the set tighter.
The surface covers the full session lifecycle, event and file-change logging, TODO resolution, memory storage/update/search, and context/history retrieval. Minor omissions like explicit memory deletion are workaroundable, so agents should not hit major dead ends.
Project memory, documentation and controlled secret access for AI coding agents.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
Persistent memory layer that saves and recalls your project context and preferences.
