session-forge 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Terrell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# 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
+
+## Quick start
+
+### Claude Code
+
+```bash
+claude mcp add session-forge -- npx session-forge
+```
+
+### Cursor / Windsurf
+
+Add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "session-forge": {
+      "command": "npx",
+      "args": ["-y", "session-forge"]
+    }
+  }
+}
+```
+
+That's it. No database, no Docker, no config files.
+
+---
+
+## The 12 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 | 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 | query |
+
+### Context
+
+| Tool | Description | Required |
+|------|-------------|----------|
+| `full_context_recall` | Get everything — profile, journals, decisions, dead ends | — |
+
+---
+
+## 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 |
+| User profile | Yes | Some | No |
+| Dependencies | 2 (SDK + zod) | Varies | 5-10+ |
+| Infrastructure | Zero (plain JSON) | SQLite/ONNX/Vector DB | PostgreSQL + Redis |
+| Tools | 12 focused | 4-9 | 37+ |
+
+---
+
+## 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:
+```
+~/.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
+```
+
+---
+
+## 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
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+Built by [Jacob Terrell](https://github.com/jacobterrell)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerSessionTools } from "./tools/sessions.js";
+import { registerProfileTools } from "./tools/profile.js";
+import { registerJournalTools } from "./tools/journal.js";
+import { registerDecisionTools } from "./tools/decisions.js";
+import { registerDeadEndTools } from "./tools/dead-ends.js";
+import { registerContextTools } from "./tools/context.js";
+const VERSION = "1.0.0";
+const server = new McpServer({
+    name: "session-forge",
+    version: VERSION,
+});
+registerSessionTools(server);
+registerProfileTools(server);
+registerJournalTools(server);
+registerDecisionTools(server);
+registerDeadEndTools(server);
+registerContextTools(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`session-forge v${VERSION} running`);
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/storage/paths.d.ts

@@ -0,0 +1,11 @@
+export declare const PATHS: {
+    readonly base: string;
+    readonly profile: string;
+    readonly journal: string;
+    readonly decisions: string;
+    readonly deadEnds: string;
+    readonly sessions: string;
+    readonly activeSession: string;
+    readonly sessionHistory: string;
+};
+//# sourceMappingURL=paths.d.ts.map

package/dist/storage/paths.js

@@ -0,0 +1,23 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+function getBaseDir() {
+    if (process.env.SESSION_FORGE_DIR) {
+        return process.env.SESSION_FORGE_DIR;
+    }
+    if (process.platform === "win32" && process.env.APPDATA) {
+        return join(process.env.APPDATA, "session-forge");
+    }
+    return join(homedir(), ".session-forge");
+}
+const base = getBaseDir();
+export const PATHS = {
+    base,
+    profile: join(base, "profile.json"),
+    journal: join(base, "journal.json"),
+    decisions: join(base, "decisions.json"),
+    deadEnds: join(base, "dead-ends.json"),
+    sessions: join(base, "sessions"),
+    activeSession: join(base, "sessions", "active.json"),
+    sessionHistory: join(base, "sessions", "history"),
+};
+//# sourceMappingURL=paths.js.map

package/dist/storage/store.d.ts

@@ -0,0 +1,5 @@
+export declare function readJson<T>(filePath: string, fallback: T): T;
+export declare function writeJson<T>(filePath: string, data: T): void;
+export declare function deleteJson(filePath: string): boolean;
+export declare function searchEntries<T>(entries: T[], query: string, textExtractor: (entry: T) => string): T[];
+//# sourceMappingURL=store.d.ts.map

package/dist/storage/store.js

@@ -0,0 +1,44 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+export function readJson(filePath, fallback) {
+    try {
+        if (!existsSync(filePath))
+            return fallback;
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+export function writeJson(filePath, data) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+}
+export function deleteJson(filePath) {
+    try {
+        if (existsSync(filePath)) {
+            unlinkSync(filePath);
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+export function searchEntries(entries, query, textExtractor) {
+    const words = query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 1);
+    if (words.length === 0)
+        return entries.slice(-20);
+    const filtered = entries.filter((entry) => {
+        const text = textExtractor(entry).toLowerCase();
+        return words.some((word) => text.includes(word));
+    });
+    return filtered.slice(-20);
+}
+//# sourceMappingURL=store.js.map

package/dist/tools/context.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerContextTools(server: McpServer): void;
+//# sourceMappingURL=context.d.ts.map

package/dist/tools/context.js

@@ -0,0 +1,50 @@
+import { PATHS } from "../storage/paths.js";
+import { readJson } from "../storage/store.js";
+const DEFAULT_PROFILE = {
+    name: null,
+    preferences: {
+        communication_style: "direct",
+        emoji_usage: "occasional",
+        technical_level: "advanced",
+        verbosity: "concise",
+    },
+    projects: [],
+    notes: [],
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+};
+export function registerContextTools(server) {
+    server.registerTool("full_context_recall", {
+        description: "Get EVERYTHING - user profile, recent sessions, decisions, dead ends. Use when starting fresh to get full context.",
+        inputSchema: {},
+    }, async () => {
+        const profile = readJson(PATHS.profile, {
+            ...DEFAULT_PROFILE,
+            created_at: new Date().toISOString(),
+            updated_at: new Date().toISOString(),
+        });
+        const journal = readJson(PATHS.journal, { sessions: [] });
+        const decisions = readJson(PATHS.decisions, {
+            decisions: [],
+        });
+        const deadEnds = readJson(PATHS.deadEnds, {
+            dead_ends: [],
+        });
+        const context = {
+            user_profile: profile,
+            recent_sessions: journal.sessions.slice(-3),
+            recent_decisions: decisions.decisions.slice(-10),
+            recent_dead_ends: deadEnds.dead_ends.slice(-10),
+            retrieved_at: new Date().toISOString(),
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(context, null, 2),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=context.js.map

package/dist/tools/dead-ends.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDeadEndTools(server: McpServer): void;
+//# sourceMappingURL=dead-ends.d.ts.map

package/dist/tools/dead-ends.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { PATHS } from "../storage/paths.js";
+import { readJson, writeJson, searchEntries } from "../storage/store.js";
+export function registerDeadEndTools(server) {
+    server.registerTool("dead_end_record", {
+        description: "Record a debugging dead end so we don't repeat it. Captures what was tried and why it failed.",
+        inputSchema: {
+            attempted: z.string().describe("What was tried"),
+            why_failed: z.string().describe("Why it didn't work"),
+            lesson: z
+                .string()
+                .optional()
+                .describe("What to remember for next time"),
+            project: z.string().optional().describe("Which project"),
+            files_involved: z
+                .array(z.string())
+                .optional()
+                .describe("Files involved"),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe("Tags for searching"),
+        },
+    }, async (params) => {
+        const data = readJson(PATHS.deadEnds, { dead_ends: [] });
+        const entry = {
+            timestamp: new Date().toISOString(),
+            attempted: params.attempted,
+            why_failed: params.why_failed,
+            lesson: params.lesson ?? "",
+            project: params.project ?? null,
+            files_involved: params.files_involved ?? [],
+            tags: params.tags ?? [],
+        };
+        data.dead_ends.push(entry);
+        if (data.dead_ends.length > 100) {
+            data.dead_ends = data.dead_ends.slice(-100);
+        }
+        writeJson(PATHS.deadEnds, data);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(entry, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("dead_end_search", {
+        description: "Search past dead ends to avoid repeating mistakes",
+        inputSchema: {
+            query: z.string().describe("Search term"),
+        },
+    }, async (params) => {
+        const data = readJson(PATHS.deadEnds, { dead_ends: [] });
+        const results = searchEntries(data.dead_ends, params.query, (d) => [
+            d.attempted,
+            d.why_failed,
+            d.lesson,
+            d.project ?? "",
+            ...d.tags,
+        ].join(" "));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(results, null, 2),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=dead-ends.js.map

package/dist/tools/decisions.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDecisionTools(server: McpServer): void;
+//# sourceMappingURL=decisions.d.ts.map

package/dist/tools/decisions.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { PATHS } from "../storage/paths.js";
+import { readJson, writeJson, searchEntries } from "../storage/store.js";
+export function registerDecisionTools(server) {
+    server.registerTool("decision_record", {
+        description: "Record a significant decision made during development. Helps future sessions understand why choices were made.",
+        inputSchema: {
+            choice: z.string().describe("What was decided"),
+            reasoning: z.string().describe("Why this choice was made"),
+            alternatives: z
+                .array(z.string())
+                .optional()
+                .describe("What other options existed"),
+            outcome: z
+                .string()
+                .optional()
+                .describe("How it turned out (can be updated later)"),
+            project: z
+                .string()
+                .optional()
+                .describe("Which project this relates to"),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe("Tags for searching later"),
+        },
+    }, async (params) => {
+        const data = readJson(PATHS.decisions, {
+            decisions: [],
+        });
+        const entry = {
+            timestamp: new Date().toISOString(),
+            choice: params.choice,
+            alternatives: params.alternatives ?? [],
+            reasoning: params.reasoning,
+            outcome: params.outcome ?? null,
+            project: params.project ?? null,
+            tags: params.tags ?? [],
+        };
+        data.decisions.push(entry);
+        if (data.decisions.length > 200) {
+            data.decisions = data.decisions.slice(-200);
+        }
+        writeJson(PATHS.decisions, data);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(entry, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("decision_search", {
+        description: "Search past decisions to understand why things are the way they are",
+        inputSchema: {
+            query: z.string().describe("Search term"),
+        },
+    }, async (params) => {
+        const data = readJson(PATHS.decisions, {
+            decisions: [],
+        });
+        const results = searchEntries(data.decisions, params.query, (d) => [d.choice, d.reasoning, d.project ?? "", ...d.tags].join(" "));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(results, null, 2),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=decisions.js.map

package/dist/tools/journal.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerJournalTools(server: McpServer): void;
+//# sourceMappingURL=journal.d.ts.map

package/dist/tools/journal.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { PATHS } from "../storage/paths.js";
+import { readJson, writeJson } from "../storage/store.js";
+export function registerJournalTools(server) {
+    server.registerTool("journal_entry", {
+        description: "Record a session journal entry capturing the journey, not just the task. Call at END of meaningful sessions to preserve context.",
+        inputSchema: {
+            summary: z
+                .string()
+                .describe("What happened this session (conversational, not just technical)"),
+            key_moments: z
+                .array(z.string())
+                .optional()
+                .describe("Significant moments - breakthroughs, realizations, fun exchanges"),
+            emotional_context: z
+                .string()
+                .optional()
+                .describe("How did the session feel? User concerns, celebrations, frustrations"),
+            breakthroughs: z
+                .array(z.string())
+                .optional()
+                .describe("What clicked or worked unexpectedly well"),
+            frustrations: z
+                .array(z.string())
+                .optional()
+                .describe("What was difficult or annoying"),
+            collaboration_notes: z
+                .string()
+                .optional()
+                .describe("Notes about working together - user preferences observed, rapport"),
+        },
+    }, async (params) => {
+        const data = readJson(PATHS.journal, { sessions: [] });
+        const entry = {
+            timestamp: new Date().toISOString(),
+            session_summary: params.summary,
+            key_moments: params.key_moments ?? [],
+            emotional_context: params.emotional_context ?? null,
+            breakthroughs: params.breakthroughs ?? [],
+            frustrations: params.frustrations ?? [],
+            collaboration_notes: params.collaboration_notes ?? null,
+        };
+        data.sessions.push(entry);
+        if (data.sessions.length > 100) {
+            data.sessions = data.sessions.slice(-100);
+        }
+        writeJson(PATHS.journal, data);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(entry, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("journal_recall", {
+        description: "Retrieve recent session context and journeys. Call at START of sessions to remember the relationship.",
+        inputSchema: {
+            sessions_count: z
+                .number()
+                .optional()
+                .describe("How many recent sessions to retrieve (default 3)"),
+        },
+    }, async (params) => {
+        const data = readJson(PATHS.journal, { sessions: [] });
+        const count = params.sessions_count ?? 3;
+        const recent = data.sessions.slice(-count);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(recent, null, 2),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=journal.js.map

package/dist/tools/profile.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerProfileTools(server: McpServer): void;
+//# sourceMappingURL=profile.d.ts.map

package/dist/tools/profile.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { PATHS } from "../storage/paths.js";
+import { readJson, writeJson } from "../storage/store.js";
+const DEFAULT_PROFILE = {
+    name: null,
+    preferences: {
+        communication_style: "direct",
+        emoji_usage: "occasional",
+        technical_level: "advanced",
+        verbosity: "concise",
+    },
+    projects: [],
+    notes: [],
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+};
+export function registerProfileTools(server) {
+    server.registerTool("profile_get", {
+        description: "Get the current user profile",
+        inputSchema: {},
+    }, async () => {
+        const profile = readJson(PATHS.profile, {
+            ...DEFAULT_PROFILE,
+            created_at: new Date().toISOString(),
+            updated_at: new Date().toISOString(),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(profile, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("profile_update", {
+        description: "Update user profile with preferences, notes, or project info. Call when learning something about the user.",
+        inputSchema: {
+            name: z.string().optional().describe("User's name if learned"),
+            preferences: z
+                .record(z.string())
+                .optional()
+                .describe("Preferences like {communication_style, emoji_usage, technical_level, verbosity}"),
+            add_project: z
+                .string()
+                .optional()
+                .describe("Add a project name to user's project list"),
+            add_note: z
+                .string()
+                .optional()
+                .describe("Add a note about the user (observations, preferences)"),
+        },
+    }, async (params) => {
+        const profile = readJson(PATHS.profile, {
+            ...DEFAULT_PROFILE,
+            created_at: new Date().toISOString(),
+            updated_at: new Date().toISOString(),
+        });
+        if (params.name) {
+            profile.name = params.name;
+        }
+        if (params.preferences) {
+            profile.preferences = { ...profile.preferences, ...params.preferences };
+        }
+        if (params.add_project && !profile.projects.includes(params.add_project)) {
+            profile.projects.push(params.add_project);
+        }
+        if (params.add_note) {
+            profile.notes.push({
+                content: params.add_note,
+                timestamp: new Date().toISOString(),
+            });
+            if (profile.notes.length > 50) {
+                profile.notes = profile.notes.slice(-50);
+            }
+        }
+        profile.updated_at = new Date().toISOString();
+        writeJson(PATHS.profile, profile);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(profile, null, 2),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=profile.js.map

package/dist/tools/sessions.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSessionTools(server: McpServer): void;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/tools/sessions.js

@@ -0,0 +1,156 @@
+import { z } from "zod";
+import { join } from "node:path";
+import { PATHS } from "../storage/paths.js";
+import { readJson, writeJson, deleteJson } from "../storage/store.js";
+function archiveCheckpoint(checkpoint) {
+    const safeName = checkpoint.timestamp.replace(/[:.]/g, "-");
+    const archivePath = join(PATHS.sessionHistory, `session_${safeName}.json`);
+    writeJson(archivePath, checkpoint);
+}
+export function registerSessionTools(server) {
+    server.registerTool("session_checkpoint", {
+        description: "Save current session state. Call this every 3-5 tool calls to protect against UI crashes. Required: task, intent, next_steps",
+        inputSchema: {
+            task: z.string().describe("Brief task name"),
+            intent: z.string().describe("What you are trying to accomplish"),
+            next_steps: z.array(z.string()).describe("Planned next steps"),
+            status: z
+                .enum(["IN_PROGRESS", "BLOCKED", "WAITING_USER"])
+                .optional()
+                .describe("Current status"),
+            files_touched: z
+                .array(z.string())
+                .optional()
+                .describe("File paths modified"),
+            recent_actions: z
+                .array(z.string())
+                .optional()
+                .describe("Last 3-5 actions"),
+            context: z
+                .record(z.unknown())
+                .optional()
+                .describe("Any important state/variables"),
+            tool_call_count: z
+                .number()
+                .optional()
+                .describe("Approx tool calls so far"),
+        },
+    }, async (params) => {
+        const checkpoint = {
+            timestamp: new Date().toISOString(),
+            task: params.task,
+            intent: params.intent,
+            status: params.status ?? "IN_PROGRESS",
+            files_touched: params.files_touched ?? [],
+            recent_actions: params.recent_actions ?? [],
+            next_steps: params.next_steps,
+            context: params.context ?? {},
+            tool_call_count: params.tool_call_count ?? 0,
+        };
+        writeJson(PATHS.activeSession, checkpoint);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        message: `Checkpoint saved at ${checkpoint.timestamp}`,
+                        checkpoint_id: checkpoint.timestamp,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("session_restore", {
+        description: "Check for interrupted work from a previous session. Call this FIRST at the start of any session.",
+        inputSchema: {},
+    }, async () => {
+        const checkpoint = readJson(PATHS.activeSession, null);
+        if (!checkpoint) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            has_active_session: false,
+                            message: "No active session found. Starting fresh.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const ageHours = (Date.now() - new Date(checkpoint.timestamp).getTime()) /
+            (1000 * 60 * 60);
+        if (ageHours > 24) {
+            archiveCheckpoint(checkpoint);
+            deleteJson(PATHS.activeSession);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            has_active_session: false,
+                            message: `Found stale session from ${checkpoint.timestamp} (${Math.round(ageHours)}h ago). Archived it. Starting fresh.`,
+                            archived: true,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const ageMinutes = Math.round(ageHours * 60);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        has_active_session: true,
+                        ...checkpoint,
+                        age_minutes: ageMinutes,
+                        message: `Found active session: "${checkpoint.task}" (${ageMinutes}m ago, ${checkpoint.tool_call_count} tool calls)`,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("session_complete", {
+        description: "Mark the current session as complete. Call this when a task is finished.",
+        inputSchema: {
+            summary: z
+                .string()
+                .optional()
+                .describe("Brief summary of what was accomplished"),
+        },
+    }, async (params) => {
+        const checkpoint = readJson(PATHS.activeSession, null);
+        if (!checkpoint) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            message: "No active checkpoint to complete",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        checkpoint.status = "COMPLETED";
+        checkpoint.completed_at = new Date().toISOString();
+        checkpoint.summary = params.summary ?? "Task completed";
+        archiveCheckpoint(checkpoint);
+        deleteJson(PATHS.activeSession);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        message: `Session completed and archived: "${checkpoint.task}"`,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=sessions.js.map

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+export interface UserPreferences {
+    communication_style: string;
+    emoji_usage: string;
+    technical_level: string;
+    verbosity: string;
+    [key: string]: string;
+}
+export interface UserNote {
+    content: string;
+    timestamp: string;
+}
+export interface UserProfile {
+    name: string | null;
+    preferences: UserPreferences;
+    projects: string[];
+    notes: UserNote[];
+    created_at: string;
+    updated_at: string;
+}
+export interface JournalEntry {
+    timestamp: string;
+    session_summary: string;
+    key_moments: string[];
+    emotional_context: string | null;
+    breakthroughs: string[];
+    frustrations: string[];
+    collaboration_notes: string | null;
+}
+export interface JournalData {
+    sessions: JournalEntry[];
+}
+export interface DecisionEntry {
+    timestamp: string;
+    choice: string;
+    alternatives: string[];
+    reasoning: string;
+    outcome: string | null;
+    project: string | null;
+    tags: string[];
+}
+export interface DecisionsData {
+    decisions: DecisionEntry[];
+}
+export interface DeadEndEntry {
+    timestamp: string;
+    attempted: string;
+    why_failed: string;
+    lesson: string;
+    project: string | null;
+    files_involved: string[];
+    tags: string[];
+}
+export interface DeadEndsData {
+    dead_ends: DeadEndEntry[];
+}
+export interface SessionCheckpoint {
+    timestamp: string;
+    task: string;
+    intent: string;
+    status: string;
+    files_touched: string[];
+    recent_actions: string[];
+    next_steps: string[];
+    context: Record<string, unknown>;
+    tool_call_count: number;
+    completed_at?: string;
+    summary?: string;
+}
+export interface FullContext {
+    user_profile: UserProfile;
+    recent_sessions: JournalEntry[];
+    recent_decisions: DecisionEntry[];
+    recent_dead_ends: DeadEndEntry[];
+    retrieved_at: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,3 @@
+// ---- Profile ----
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "session-forge",
+  "version": "1.0.0",
+  "description": "Session intelligence for AI coding assistants. Persistent memory, decisions, dead ends, crash recovery. Zero infrastructure.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "session-forge": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "windsurf",
+    "ai-memory",
+    "session-management",
+    "dead-ends",
+    "decisions",
+    "coding-assistant",
+    "developer-tools"
+  ],
+  "author": "Jacob Terrell",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jacobterrell/session-forge"
+  },
+  "homepage": "https://github.com/jacobterrell/session-forge#readme",
+  "bugs": {
+    "url": "https://github.com/jacobterrell/session-forge/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1"
+  }
+}