session-forge

Never start from zero. Persistent session intelligence for AI coding assistants.

Session-forge gives your AI coding assistant memory that survives across sessions. It tracks decisions, dead ends, user preferences, and session state — so every conversation builds on the last one instead of starting from scratch.

Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

What it does

Session crash recovery — checkpoint your work, pick up where you left off
Decision logging — record why you chose X over Y, search it later
Dead end tracking — never repeat the same debugging mistake twice
User profile — AI remembers your name, preferences, and projects
Session journal — capture the journey, not just the task
Full context recall — bootstrap a new session with everything in one call
Data management — prune old entries, export all data, view stats

Quick start

Claude Code

Terminal

claude mcp add session-forge -- npx session-forge

Cursor / Windsurf

Add to your MCP settings:

config.json

{
  "mcpServers": {
    "session-forge": {
      "command": "npx",
      "args": ["-y", "session-forge"]
    }
  }
}

That's it. No database, no Docker, no config files.

The 15 tools

Sessions

Tool	Description	Required
`session_checkpoint`	Save work-in-progress state for crash recovery	task, intent, next_steps
`session_restore`	Check for interrupted work from a previous session	—
`session_complete`	Archive session and mark complete	—

Profile

Tool	Description	Required
`profile_get`	Get the current user profile	—
`profile_update`	Update name, preferences, projects, or notes	—

Journal

Tool	Description	Required
`journal_entry`	Record session summary with breakthroughs and frustrations	summary
`journal_recall`	Retrieve recent session journals	—

Decisions

Tool	Description	Required
`decision_record`	Log a significant decision with alternatives and reasoning	choice, reasoning
`decision_search`	Search past decisions by keyword (supports `limit` param)	query

Dead Ends

Tool	Description	Required
`dead_end_record`	Log a failed approach and the lesson learned	attempted, why_failed
`dead_end_search`	Search past dead ends to avoid repeating mistakes (supports `limit` param)	query

Context

Tool	Description	Required
`full_context_recall`	Get everything — profile, journals, decisions, dead ends. Supports optional `project` filter.	—

Data Management

Tool	Description	Required
`data_manage`	Prune old entries, export all data, clear stores, or view stats	action
`data_list`	Browse stored entries with numbered summaries. Supports search filter.	store
`data_delete`	Delete a specific entry by index from `data_list` output	store, entry_index

data_manage actions:

stats — entry counts and schema versions for all stores
export — dump all data as JSON
prune — remove entries older than N days (default: 90)
clear — wipe a specific store (journal, decisions, dead_ends, profile, or all)

data_list + data_delete workflow:

data_list with store="decisions" — see numbered list of all decisions
data_list with store="decisions", query="minecraft" — filter by keyword
data_delete with store="decisions", entry_index=3 — remove entry #3 from the list

Why session-forge?

	session-forge	Basic memory MCPs	Enterprise tools
Setup	`npx session-forge`	Varies	Docker + databases
Dead end tracking	Yes	No	No
Decision logging	Yes	No	Some
Session crash recovery	Yes	Some	Yes
Data management	Yes	No	Some
User profile	Yes	Some	No
Dependencies	2 (SDK + zod)	Varies	5-10+
Infrastructure	Zero (plain JSON)	SQLite/ONNX/Vector DB	PostgreSQL + Redis
Tools	15 focused	4-9	37+

Configuration

Environment variables

Variable	Default	Description
`SESSION_FORGE_DIR`	`~/.session-forge` or `%APPDATA%\session-forge`	Override data storage location
`SESSION_FORGE_STALE_HOURS`	`24`	Hours before an inactive session is auto-archived

Storage

All data is stored locally as plain JSON files:

Platform	Location
Linux / macOS	`~/.session-forge/`
Windows	`%APPDATA%\session-forge\`

Override with the SESSION_FORGE_DIR environment variable:

bash

SESSION_FORGE_DIR=/custom/path npx session-forge

Files:

Code

~/.session-forge/
  profile.json        # User preferences and projects
  journal.json        # Session summaries (last 100)
  decisions.json      # Decision log (last 200)
  dead-ends.json      # Failed approaches (last 100)
  sessions/
    active.json       # Current checkpoint
    history/          # Archived sessions

Data files include a schema_version field for future migration support.

CLAUDE.md template

Add this to your project's CLAUDE.md to teach the AI when to call each tool:

markdown

## Session Flow

### Fresh session
1. Call `full_context_recall` — get profile, journals, decisions, dead ends
2. Call `session_restore` — check for interrupted work

### During work
- `decision_record` — when making a significant architectural choice
- `dead_end_record` — when something fails and we learn why
- `session_checkpoint` — every 10-15 tool calls during long sessions

### Session end
1. Call `journal_entry` — record what happened
2. Call `session_complete` — archive the checkpoint

Changelog

v2.0.1

Added disclaimer: session-forge is NOT affiliated with SessionForge LLC (sessionforge.dev)

v2.0.0

Knowledge Graph — link decisions and dead ends together with related_dead_ends and led_to_decision fields
Scored Search — fuzzy matching, tag filtering, AND/OR search modes, relevance scoring (replaces basic string matching)
Usage Stats — tracks dead ends avoided, searches performed, sessions recovered
MEMORY.md Sync — full_context_recall can read your MEMORY.md and suggest decisions/dead ends that should be saved to memory
Enhanced Checkpoints — now tracks errors_encountered, key_findings, decisions_made, dead_ends_hit
New storage modules: links.js, search.js, stats.js, migrate.js
Schema bumped to v2

v1.2.0

Added data_list tool — browse stored entries with numbered summaries, optional search filter
Added data_delete tool — surgically remove individual entries by index
Users can now see exactly what's stored and delete anything they want

v1.1.0

Added data_manage tool (stats, export, prune by age, clear per-store)
Added project filter to full_context_recall
Added limit param to decision_search and dead_end_search
Added error logging to JSON reads (was silently swallowing parse failures)
Added configurable stale session timeout via SESSION_FORGE_STALE_HOURS
Added schema_version to data files for future migration support
Fixed version mismatch between code and package.json

v1.0.2

Initial public release

License

MIT

Important Notice

session-forge is NOT affiliated with SessionForge LLC (sessionforge.dev).

session-forge was first published on npm on February 7, 2026 — before SessionForge LLC appeared. We have no connection to their product or company.

Here's why this matters: session-forge stores all your data locally on your machine as plain JSON files. Nothing leaves your computer. No accounts, no servers, no third parties.

Any service asking you to route your AI session data, coding habits, and terminal access through their servers should make you ask: who has access to that data, and what are they doing with it?

Your workflow, your decisions, your code — that's yours. It should stay on your machine, under your control. That's how session-forge was built and that's how it will stay.

Built by Jacob Terrell