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

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

Cursor / Windsurf

Add to your MCP settings:

{
  "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:

1. data_list with store="decisions" — see numbered list of all decisions
2. data_list with store="decisions", query="minecraft" — filter by keyword
3. 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:

SESSION_FORGE_DIR=/custom/path npx session-forge

Files:

~/.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:

## 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