context-stash 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Taylor
+
+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,442 @@
+# context-stash
+
+A workspace-scoped MCP server that provides a durable, Git-native memory layer for AI coding agents.
+
+> **The missing piece in AI-assisted software development**: Give AI agents persistent memory of *why* changes were made.
+
+## Overview
+
+**context-stash** stores atomic context entries as Markdown files inside a `.context/` directory at the root of your project. AI agents reference these entries in code comments (e.g., `// refer to context 00012`) to preserve reasoning and avoid reintroducing historical bugs.
+
+## Why context-stash?
+
+### The Problem: AI Forgets
+
+Every AI coding assistant today suffers from the same flaw: **no persistent memory of past decisions**. This leads to:
+
+- 🔄 Reintroduced bugs the AI fixed yesterday
+- 🤔 Repeated questions about architectural decisions
+- 💥 Breaking changes that ignore historical constraints
+- 📝 Lost context between sessions, models, and tools
+
+### The Solution: A Reasoning Ledger
+
+context-stash creates a **distributed, code-embedded reference system** that works like:
+
+- Git commit messages (explains *what* changed)
+- Architectural Decision Records (explains *why* it changed)
+- Inline documentation (stays with the code)
+- AI reasoning logs (durable across sessions)
+
+**All unified into a single, simple mechanism.**
+
+### Why It Works
+
+🧠 **Persistent Memory** - Context survives sessions, models, and tools  
+🔗 **Cross-File References** - One decision can explain changes in multiple files  
+📖 **Human-Readable** - Markdown files anyone can read and audit  
+🔒 **Immutable by Design** - Historical reasoning stays accurate  
+🌍 **Universal** - Works with any MCP-compatible AI agent  
+🚀 **Git-Native** - Version control for both code *and* reasoning
+
+## What Makes It Different
+
+### A Shared Language Between Humans and AI
+
+Most AI tooling is either:
+- **AI-only** (humans can't read it), or
+- **Human-only** (AI ignores it)
+
+context-stash is both:
+- ✍️ **AI-generated** - Agents create context automatically
+- 🤖 **AI-consumable** - Agents retrieve it on demand
+- 👁️ **Human-readable** - Plain Markdown anyone can understand
+- ✏️ **Human-editable** - Edit manually when needed
+- 📚 **Git-tracked** - Full history of reasoning over time
+
+### Simple, Standard-Ready Design
+
+Like `.gitignore`, `.editorconfig`, and `README.md`, context-stash is:
+- Small, obvious, and useful
+- Editor-agnostic and model-agnostic
+- Easy to adopt, easy to ignore
+- Non-intrusive to existing workflows
+
+**This is how standards emerge.**
+
+## Links
+
+- 🌐 **Website**: [https://nzmarktaylor.github.io/context-stash/](https://nzmarktaylor.github.io/context-stash/)
+- 📦 **npm**: [https://www.npmjs.com/package/context-stash](https://www.npmjs.com/package/context-stash)
+- 💻 **GitHub**: [https://github.com/nzmarktaylor/context-stash](https://github.com/nzmarktaylor/context-stash)
+- 📖 **Examples**: [EXAMPLES.md](EXAMPLES.md)
+- 🔧 **Development**: [DEVELOPMENT.md](DEVELOPMENT.md)
+
+## Features
+
+- 🧠 **Persistent Memory** - Store reasoning, decisions, and context across AI coding sessions
+- 🔒 **Immutable Entries** - Context entries are write-once, preventing accidental modifications
+- 📦 **Git-Native** - Plain Markdown files that work seamlessly with version control
+- 🔍 **Search & Discovery** - Find relevant context through keyword search
+- 🛠️ **MCP Compatible** - Works with any MCP-compatible AI coding agent
+- ⚡ **Zero Config** - Sensible defaults with optional customization
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g context-stash
+```
+
+### Project-Specific Installation
+
+```bash
+npm install --save-dev context-stash
+```
+
+## Quick Start
+
+### 1. Initialize Your Workspace
+
+Navigate to your project root and run:
+
+```bash
+context-stash --init
+```
+
+This creates:
+- `.context/` directory for storing context entries
+- `.context/config.json` with default configuration
+- `agents.md` with usage instructions for AI agents
+
+### 2. Configure Your AI Agent
+
+Add context-stash to your AI agent's MCP server configuration. For example, in Claude Desktop's config:
+
+```json
+{
+  "mcpServers": {
+    "context-stash": {
+      "command": "context-stash",
+      "args": ["--serve"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+### 3. Start Using Context
+
+Your AI agent can now:
+- **Create context entries**: `context.create` with Markdown content
+- **Retrieve entries**: `context.get` with a reference number
+- **List all entries**: `context.list`
+- **Search entries**: `context.search` with a keyword
+
+## Usage Pattern
+
+### Creating Context Entries
+
+When making a meaningful code change, create a context entry:
+
+```
+Agent calls: context.create
+Input: { "markdown": "# Fix: Null Pointer in User Service\n\nAdded null check before accessing user.profile..." }
+Output: { "file": "00012.md" }
+```
+
+### Referencing Context in Code
+
+Add comments to reference context:
+
+```javascript
+// refer to context 00012
+function getUserProfile(user) {
+  if (!user || !user.profile) return null;
+  return user.profile;
+}
+```
+
+### Multiple References
+
+A single context entry can be referenced in multiple files, and code can reference multiple entries:
+
+```python
+# refer to context 00012, 00019, 00101
+def process_user_data(user):
+    # ...
+```
+
+## MCP Tools
+
+### `context.create`
+
+Create a new immutable context entry.
+
+**Input:**
+```json
+{
+  "markdown": "string (max 50 lines by default)"
+}
+```
+
+**Output:**
+```json
+{
+  "file": "00012.md"
+}
+```
+
+### `context.get`
+
+Retrieve a context entry by reference.
+
+**Input:**
+```json
+{
+  "ref": "00012"
+}
+```
+
+**Output:**
+```json
+{
+  "markdown": "# Fix: Null Pointer in User Service\n..."
+}
+```
+
+### `context.list`
+
+List all context entries.
+
+**Output:**
+```json
+{
+  "entries": [
+    { "ref": "00001", "file": "00001.md" },
+    { "ref": "00002", "file": "00002.md" }
+  ]
+}
+```
+
+### `context.search`
+
+Search context entries by keyword.
+
+**Input:**
+```json
+{
+  "query": "null pointer"
+}
+```
+
+**Output:**
+```json
+{
+  "results": [
+    {
+      "ref": "00012",
+      "file": "00012.md",
+      "snippet": "Added null check before accessing user.profile..."
+    }
+  ]
+}
+```
+
+## Configuration
+
+The `.context/config.json` file controls behavior:
+
+```json
+{
+  "maxLines": 50,
+  "startIndex": 1,
+  "leadingZeros": 5,
+  "filePrefix": "",
+  "fileSuffix": ".md"
+}
+```
+
+### Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `maxLines` | Maximum lines allowed per context entry | `50` |
+| `startIndex` | First index number to use | `1` |
+| `leadingZeros` | Number of digits in filenames | `5` |
+| `filePrefix` | Optional filename prefix | `""` |
+| `fileSuffix` | File extension | `".md"` |
+
+### Custom Filename Format
+
+Adjust the config to use custom naming:
+
+```json
+{
+  "filePrefix": "ctx-",
+  "fileSuffix": ".markdown",
+  "leadingZeros": 4
+}
+```
+
+This produces filenames like: `ctx-0123.markdown`
+
+## CLI Commands
+
+### `--init`
+
+Initialize a workspace with context-stash:
+
+```bash
+context-stash --init
+```
+
+### `--serve`
+
+Start the MCP server (typically called by your AI agent):
+
+```bash
+context-stash --serve
+```
+
+### `--help`
+
+Show help information:
+
+```bash
+context-stash --help
+```
+
+## Best Practices
+
+### Keep Entries Atomic
+
+Each context entry should explain one conceptual change or decision:
+
+✅ **Good:**
+```markdown
+# Fix: Race Condition in Payment Processing
+
+Added mutex lock around balance update to prevent concurrent modifications
+that could result in incorrect balance calculations.
+```
+
+❌ **Bad:**
+```markdown
+# Various Changes
+
+Fixed payment bug, updated user service, refactored database layer...
+```
+
+### Entries Are Immutable
+
+Never modify existing context entries. If you need to add more information, create a new entry:
+
+```javascript
+// refer to context 00012, 00045
+// Context 00012: Original fix
+// Context 00045: Additional edge case handling
+```
+
+### Use Descriptive Titles
+
+Start each entry with a clear title:
+
+```markdown
+# Decision: Use PostgreSQL Instead of MongoDB
+
+After evaluating both databases, chose PostgreSQL because...
+```
+
+### When to Create Context
+
+Create context entries to capture:
+
+- 🐛 **Bug Fixes**: What broke, why it broke, how you fixed it
+- 🎯 **Design Decisions**: Why you chose approach A over B
+- ⚠️ **Workarounds**: Why the "proper" solution wasn't feasible
+- 🔄 **Refactoring**: What assumptions changed
+- 🚫 **Deprecated Code**: What future AI should avoid
+- 🧱 **Constraints**: What limitations influenced the design
+- 💡 **Intent**: What the code is *trying* to accomplish
+
+**Think of it as a reasoning ledger, not just a change log.**
+
+## Version Control
+
+The `.context/` directory is designed to work with Git:
+
+### Recommended `.gitignore`
+
+Most teams should commit context entries:
+
+```gitignore
+# Don't ignore .context/ - it's valuable project documentation!
+```
+
+### When to Ignore
+
+Only ignore if your context contains sensitive information:
+
+```gitignore
+.context/
+```
+
+## Requirements
+
+- **Node.js**: >= 18.0.0
+- **Operating System**: Windows, macOS, Linux
+
+## Development
+
+### Building from Source
+
+```bash
+git clone https://github.com/nzmarktaylor/context-stash.git
+cd context-stash
+npm install
+npm run build
+```
+
+### Testing Locally
+
+```bash
+npm link
+cd /path/to/test/project
+context-stash --init
+```
+
+## Troubleshooting
+
+### "Failed to load config" Error
+
+Make sure you've initialized the workspace:
+
+```bash
+context-stash --init
+```
+
+### MCP Server Not Responding
+
+Ensure the server is launched with the correct working directory (your project root).
+
+### Context Entry Too Long
+
+Reduce the markdown content or increase `maxLines` in `.context/config.json`.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Credits
+
+Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk).
+
+---
+
+**Note**: This is a workspace-scoped MCP server. It must be launched per workspace, not globally, and is sandboxed to the workspace root for security.

package/dist/cli.d.ts

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

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { initializeWorkspace } from './utils.js';
+import { startServer } from './server.js';
+const args = process.argv.slice(2);
+// refer to context 00001
+async function main() {
+    if (args.includes('--init')) {
+        // Initialize workspace
+        const workspaceRoot = process.cwd();
+        await initializeWorkspace(workspaceRoot);
+    }
+    else if (args.includes('--serve')) {
+        // Start MCP server
+        await startServer();
+    }
+    else if (args.includes('--help') || args.includes('-h')) {
+        // Show help
+        console.log(`
+context-stash - A workspace-scoped MCP server for AI coding agents
+
+USAGE:
+  context-stash --init     Initialize workspace with .context/ directory
+  context-stash --serve    Start the MCP server (stdio transport)
+  context-stash --help     Show this help message
+
+DESCRIPTION:
+  context-stash provides a durable, Git-native memory layer for AI coding
+  agents. It stores atomic context entries as Markdown files inside a
+  .context/ directory at the root of your project.
+
+INITIALIZATION:
+  Run 'context-stash --init' in your project root to create:
+    - .context/            Directory for context entries
+    - .context/config.json Configuration file
+    - agents.md            Usage instructions for AI agents
+
+MCP SERVER:
+  The MCP server provides four tools:
+    - context.create       Create a new context entry
+    - context.get          Retrieve a context entry by reference
+    - context.list         List all context entries
+    - context.search       Search context entries by keyword
+
+  The server must be launched with the workspace root as the working directory.
+
+EXAMPLES:
+  # Initialize a new workspace
+  cd /path/to/your/project
+  context-stash --init
+
+  # Start the MCP server (typically configured in your AI agent)
+  context-stash --serve
+
+MORE INFO:
+  https://github.com/yourusername/context-stash
+`);
+    }
+    else {
+        console.error('Unknown command. Use --help for usage information.');
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error('Error:', error.message);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,yBAAyB;AACzB,KAAK,UAAU,IAAI;IACjB,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,uBAAuB;QACvB,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;QACpC,MAAM,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAC3C,CAAC;SAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACpC,mBAAmB;QACnB,MAAM,WAAW,EAAE,CAAC;IACtB,CAAC;SAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1D,YAAY;QACZ,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCf,CAAC,CAAC;IACD,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createServer, startServer } from './server.js';
+export { initializeWorkspace, loadConfig, saveConfig } from './utils.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACzE,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createServer, startServer } from './server.js';
+export { initializeWorkspace, loadConfig, saveConfig } from './utils.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACzE,cAAc,YAAY,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+/**
+ * Create and configure the MCP server
+ */
+export declare function createServer(): Server;
+/**
+ * Start the MCP server
+ */
+export declare function startServer(): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAqBnE;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAyGrC;AAoLD;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAOjD"}

package/dist/server.js

@@ -0,0 +1,268 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { loadConfig, formatFilename, extractRef, getNextIndex, countLines, validatePath, } from './utils.js';
+const CONTEXT_DIR = '.context';
+const workspaceRoot = process.cwd();
+/**
+ * Create and configure the MCP server
+ */
+export function createServer() {
+    const server = new Server({
+        name: 'context-stash',
+        version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // List available tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: [
+                {
+                    name: 'context.create',
+                    description: 'Create a new immutable context entry',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            markdown: {
+                                type: 'string',
+                                description: 'Markdown content for the context entry',
+                            },
+                        },
+                        required: ['markdown'],
+                    },
+                },
+                {
+                    name: 'context.get',
+                    description: 'Retrieve the contents of a context entry',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            ref: {
+                                type: 'string',
+                                description: 'Reference number (e.g., "00012")',
+                            },
+                        },
+                        required: ['ref'],
+                    },
+                },
+                {
+                    name: 'context.list',
+                    description: 'List all context entries',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {},
+                    },
+                },
+                {
+                    name: 'context.search',
+                    description: 'Search context entries by keyword',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            query: {
+                                type: 'string',
+                                description: 'Search query string',
+                            },
+                        },
+                        required: ['query'],
+                    },
+                },
+            ],
+        };
+    });
+    // Handle tool calls
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        try {
+            switch (request.params.name) {
+                case 'context.create':
+                    return await handleCreate(request.params.arguments);
+                case 'context.get':
+                    return await handleGet(request.params.arguments);
+                case 'context.list':
+                    return await handleList();
+                case 'context.search':
+                    return await handleSearch(request.params.arguments);
+                default:
+                    throw new Error(`Unknown tool: ${request.params.name}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}
+/**
+ * Handle context.create tool
+ */
+async function handleCreate(args) {
+    const { markdown } = args;
+    if (typeof markdown !== 'string') {
+        throw new Error('markdown must be a string');
+    }
+    // Load config
+    const config = await loadConfig(workspaceRoot);
+    // Validate line count
+    const lineCount = countLines(markdown);
+    if (lineCount > config.maxLines) {
+        throw new Error(`Markdown exceeds maximum of ${config.maxLines} lines (got ${lineCount} lines)`);
+    }
+    // Get next index and format filename
+    const index = await getNextIndex(workspaceRoot, config);
+    const filename = formatFilename(index, config);
+    const filePath = path.join(workspaceRoot, CONTEXT_DIR, filename);
+    // Validate path
+    validatePath(filePath, workspaceRoot);
+    // Write file
+    await fs.writeFile(filePath, markdown, 'utf-8');
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ file: filename }, null, 2),
+            },
+        ],
+    };
+}
+/**
+ * Handle context.get tool
+ */
+async function handleGet(args) {
+    const { ref } = args;
+    if (typeof ref !== 'string') {
+        throw new Error('ref must be a string');
+    }
+    // Load config
+    const config = await loadConfig(workspaceRoot);
+    // Determine filename
+    const filename = `${config.filePrefix}${ref}${config.fileSuffix}`;
+    const filePath = path.join(workspaceRoot, CONTEXT_DIR, filename);
+    // Validate path
+    validatePath(filePath, workspaceRoot);
+    // Read file
+    try {
+        const markdown = await fs.readFile(filePath, 'utf-8');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ markdown }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Context entry '${ref}' not found`);
+    }
+}
+/**
+ * Handle context.list tool
+ */
+async function handleList() {
+    // Load config
+    const config = await loadConfig(workspaceRoot);
+    const contextDir = path.join(workspaceRoot, CONTEXT_DIR);
+    try {
+        const files = await fs.readdir(contextDir);
+        const entries = [];
+        for (const file of files) {
+            if (file === 'config.json')
+                continue;
+            const ref = extractRef(file, config);
+            if (ref) {
+                entries.push({ ref, file });
+            }
+        }
+        // Sort by index
+        entries.sort((a, b) => {
+            const indexA = parseInt(a.ref, 10);
+            const indexB = parseInt(b.ref, 10);
+            return indexA - indexB;
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ entries }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error('Failed to list context entries');
+    }
+}
+/**
+ * Handle context.search tool
+ */
+async function handleSearch(args) {
+    const { query } = args;
+    if (typeof query !== 'string') {
+        throw new Error('query must be a string');
+    }
+    // Load config
+    const config = await loadConfig(workspaceRoot);
+    const contextDir = path.join(workspaceRoot, CONTEXT_DIR);
+    const results = [];
+    try {
+        const files = await fs.readdir(contextDir);
+        for (const file of files) {
+            if (file === 'config.json')
+                continue;
+            const ref = extractRef(file, config);
+            if (!ref)
+                continue;
+            const filePath = path.join(contextDir, file);
+            const content = await fs.readFile(filePath, 'utf-8');
+            // Simple case-insensitive search
+            const lines = content.split('\n');
+            const lowerQuery = query.toLowerCase();
+            for (const line of lines) {
+                if (line.toLowerCase().includes(lowerQuery)) {
+                    results.push({
+                        ref,
+                        file,
+                        snippet: line.trim(),
+                    });
+                    break; // Only include first match per file
+                }
+            }
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ results }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error('Failed to search context entries');
+    }
+}
+/**
+ * Start the MCP server
+ */
+export async function startServer() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Keep process running
+    process.stdin.resume();
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Configuration for context-stash
+ */
+export interface Config {
+    maxLines: number;
+    startIndex: number;
+    leadingZeros: number;
+    filePrefix: string;
+    fileSuffix: string;
+}
+/**
+ * Represents a context entry reference
+ */
+export interface ContextEntry {
+    ref: string;
+    file: string;
+}
+/**
+ * Result of a context search
+ */
+export interface SearchResult {
+    ref: string;
+    file: string;
+    snippet: string;
+}
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_CONFIG: Config;
+/**
+ * Default agents.md content
+ */
+export declare const AGENTS_MD_CONTENT = "# Context Stash (MCP Tool)\n\nThis project uses **context\u2011stash**, a workspace\u2011local MCP server that stores durable reasoning context for AI coding agents.\n\n## Purpose\n\nContext entries explain *why* code changes were made. They help prevent reintroducing historical bugs and allow AI agents to understand the intent behind modifications.\n\n## Usage Pattern\n\n- When making a meaningful code change, call the MCP tool `context.create` with a short Markdown explanation.\n- The tool returns a reference number (e.g., `00012`).\n- Insert comments in relevant files such as:\n\n```\n// refer to context 00012\n```\n\n- Context entries are **immutable**. If new reasoning is needed, create a new entry rather than modifying an old one.\n- A single context entry may be referenced in many files.\n- Code may reference multiple entries:\n\n```\n// refer to context 00012, 00019, 00101\n```\n\n## When to Create Context\n\nCreate context entries for:\n\n- **Bug Fixes**: What broke, why it broke, and how you fixed it\n- **Design Decisions**: Why you chose approach A over B\n- **Workarounds**: Why the \"proper\" solution wasn't feasible\n- **Refactoring**: What assumptions changed and why\n- **Constraints**: What limitations influenced the design\n- **Deprecated Code**: What future AI should avoid and why\n- **Intent Clarification**: What the code is trying to accomplish beyond what's obvious\n\n**Do NOT create context for:**\n- Trivial changes (formatting, typos)\n- Self-explanatory code changes\n- Temporary experiments\n- Changes that are fully explained by existing documentation\n\n## Writing Good Context\n\n### Use Clear Structure\n\n```markdown\n# Brief Title (Bug Fix / Decision / Workaround)\n\n## Problem / Context\nWhat situation led to this change?\n\n## Solution / Decision\nWhat did you do and why?\n\n## Alternatives Considered (optional)\nWhat other approaches were rejected and why?\n\n## Impact (optional)\nWhat files/systems does this affect?\n```\n\n### Be Concise But Complete\n\n- Max 50 lines by default (configurable)\n- Focus on **WHY**, not just WHAT\n- Include enough detail that future AI can understand the reasoning\n- Avoid unnecessary verbosity\n\n### Think Cross-Session\n\nRemember: You might not be the AI agent that reads this later. Write for:\n- Different AI models\n- Future versions of yourself\n- Human developers reviewing code\n- Team members unfamiliar with the change\n\n## Best Practices for AI Agents\n\n### Before Making Changes\n\n1. **Search existing context**: Use `context.search` to check if similar issues were addressed\n2. **List recent context**: Use `context.list` to see what decisions were made recently\n3. **Read referenced context**: If you see `// refer to context XXXXX`, call `context.get` to understand WHY the code exists\n\n### When Making Changes\n\n1. **Create context FIRST** if the change needs explanation\n2. **Add references IMMEDIATELY** after creating context\n3. **Be consistent** with comment format: `// refer to context 00012`\n\n### Important Reminders\n\n- **NEVER edit existing context files** in `.context/` - they are immutable\n- **ALWAYS reference context** when the reasoning isn't obvious from the code alone\n- **CHECK for existing context** before assuming you know the full story\n- **CREATE new context** if you discover additional information about an old decision\n\n## Project-Specific Guidelines\n\n### TypeScript Project\n\nThis is a TypeScript project targeting Node.js 18+. When working with this codebase:\n\n- Use explicit types for function parameters and return values\n- Prefer `async/await` over raw promises\n- Use ES modules (`import/export`) not CommonJS\n- Follow existing code style and conventions\n- Add JSDoc comments for public APIs\n\n### MCP Server Implementation\n\nKey architectural decisions for this project:\n\n- **Stdio transport**: The server uses stdio for communication (not TCP/HTTP)\n- **Workspace-scoped**: All operations must be sandboxed to `process.cwd()`\n- **Path validation**: Always validate paths to prevent directory traversal\n- **Immutability**: Context entries are write-once by design\n- **Simplicity**: The server should stay \"dumb\" - no AI interpretation, just storage\n\n### Security Considerations\n\n- Never allow path traversal outside workspace root\n- No network operations (stdio only)\n- Validate all user inputs\n- Keep dependencies minimal\n\n## MCP Server\n\nTo enable this tool, configure your agent to launch:\n\n```\ncontext-stash --serve\n```\n\nThe server must be launched with the workspace root as the working directory.\n\n## Questions?\n\nIf you're unsure whether to create context, err on the side of **creating it**. It's better to have too much reasoning documented than too little.\n";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,MAM5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,0qJA8I7B,CAAC"}

package/dist/types.js

@@ -0,0 +1,157 @@
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG = {
+    maxLines: 50,
+    startIndex: 1,
+    leadingZeros: 5,
+    filePrefix: "",
+    fileSuffix: ".md"
+};
+/**
+ * Default agents.md content
+ */
+export const AGENTS_MD_CONTENT = `# Context Stash (MCP Tool)
+
+This project uses **context‑stash**, a workspace‑local MCP server that stores durable reasoning context for AI coding agents.
+
+## Purpose
+
+Context entries explain *why* code changes were made. They help prevent reintroducing historical bugs and allow AI agents to understand the intent behind modifications.
+
+## Usage Pattern
+
+- When making a meaningful code change, call the MCP tool \`context.create\` with a short Markdown explanation.
+- The tool returns a reference number (e.g., \`00012\`).
+- Insert comments in relevant files such as:
+
+\`\`\`
+// refer to context 00012
+\`\`\`
+
+- Context entries are **immutable**. If new reasoning is needed, create a new entry rather than modifying an old one.
+- A single context entry may be referenced in many files.
+- Code may reference multiple entries:
+
+\`\`\`
+// refer to context 00012, 00019, 00101
+\`\`\`
+
+## When to Create Context
+
+Create context entries for:
+
+- **Bug Fixes**: What broke, why it broke, and how you fixed it
+- **Design Decisions**: Why you chose approach A over B
+- **Workarounds**: Why the "proper" solution wasn't feasible
+- **Refactoring**: What assumptions changed and why
+- **Constraints**: What limitations influenced the design
+- **Deprecated Code**: What future AI should avoid and why
+- **Intent Clarification**: What the code is trying to accomplish beyond what's obvious
+
+**Do NOT create context for:**
+- Trivial changes (formatting, typos)
+- Self-explanatory code changes
+- Temporary experiments
+- Changes that are fully explained by existing documentation
+
+## Writing Good Context
+
+### Use Clear Structure
+
+\`\`\`markdown
+# Brief Title (Bug Fix / Decision / Workaround)
+
+## Problem / Context
+What situation led to this change?
+
+## Solution / Decision
+What did you do and why?
+
+## Alternatives Considered (optional)
+What other approaches were rejected and why?
+
+## Impact (optional)
+What files/systems does this affect?
+\`\`\`
+
+### Be Concise But Complete
+
+- Max 50 lines by default (configurable)
+- Focus on **WHY**, not just WHAT
+- Include enough detail that future AI can understand the reasoning
+- Avoid unnecessary verbosity
+
+### Think Cross-Session
+
+Remember: You might not be the AI agent that reads this later. Write for:
+- Different AI models
+- Future versions of yourself
+- Human developers reviewing code
+- Team members unfamiliar with the change
+
+## Best Practices for AI Agents
+
+### Before Making Changes
+
+1. **Search existing context**: Use \`context.search\` to check if similar issues were addressed
+2. **List recent context**: Use \`context.list\` to see what decisions were made recently
+3. **Read referenced context**: If you see \`// refer to context XXXXX\`, call \`context.get\` to understand WHY the code exists
+
+### When Making Changes
+
+1. **Create context FIRST** if the change needs explanation
+2. **Add references IMMEDIATELY** after creating context
+3. **Be consistent** with comment format: \`// refer to context 00012\`
+
+### Important Reminders
+
+- **NEVER edit existing context files** in \`.context/\` - they are immutable
+- **ALWAYS reference context** when the reasoning isn't obvious from the code alone
+- **CHECK for existing context** before assuming you know the full story
+- **CREATE new context** if you discover additional information about an old decision
+
+## Project-Specific Guidelines
+
+### TypeScript Project
+
+This is a TypeScript project targeting Node.js 18+. When working with this codebase:
+
+- Use explicit types for function parameters and return values
+- Prefer \`async/await\` over raw promises
+- Use ES modules (\`import/export\`) not CommonJS
+- Follow existing code style and conventions
+- Add JSDoc comments for public APIs
+
+### MCP Server Implementation
+
+Key architectural decisions for this project:
+
+- **Stdio transport**: The server uses stdio for communication (not TCP/HTTP)
+- **Workspace-scoped**: All operations must be sandboxed to \`process.cwd()\`
+- **Path validation**: Always validate paths to prevent directory traversal
+- **Immutability**: Context entries are write-once by design
+- **Simplicity**: The server should stay "dumb" - no AI interpretation, just storage
+
+### Security Considerations
+
+- Never allow path traversal outside workspace root
+- No network operations (stdio only)
+- Validate all user inputs
+- Keep dependencies minimal
+
+## MCP Server
+
+To enable this tool, configure your agent to launch:
+
+\`\`\`
+context-stash --serve
+\`\`\`
+
+The server must be launched with the workspace root as the working directory.
+
+## Questions?
+
+If you're unsure whether to create context, err on the side of **creating it**. It's better to have too much reasoning documented than too little.
+`;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA4BA;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAW;IACpC,QAAQ,EAAE,EAAE;IACZ,UAAU,EAAE,CAAC;IACb,YAAY,EAAE,CAAC;IACf,UAAU,EAAE,EAAE;IACd,UAAU,EAAE,KAAK;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8IhC,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,34 @@
+import { Config } from './types.js';
+/**
+ * Load configuration from .context/config.json
+ */
+export declare function loadConfig(workspaceRoot: string): Promise<Config>;
+/**
+ * Save configuration to .context/config.json
+ */
+export declare function saveConfig(workspaceRoot: string, config: Config): Promise<void>;
+/**
+ * Initialize the context-stash workspace
+ */
+export declare function initializeWorkspace(workspaceRoot: string): Promise<void>;
+/**
+ * Format index as filename according to config
+ */
+export declare function formatFilename(index: number, config: Config): string;
+/**
+ * Extract reference number from filename
+ */
+export declare function extractRef(filename: string, config: Config): string | null;
+/**
+ * Get the next available index
+ */
+export declare function getNextIndex(workspaceRoot: string, config: Config): Promise<number>;
+/**
+ * Count lines in markdown content
+ */
+export declare function countLines(markdown: string): number;
+/**
+ * Validate path to prevent directory traversal
+ */
+export declare function validatePath(requestedPath: string, workspaceRoot: string): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAqC,MAAM,YAAY,CAAC;AAMvE;;GAEG;AACH,wBAAsB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUvE;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrF;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkC9E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU1E;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BzF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAO/E"}

package/dist/utils.js

@@ -0,0 +1,128 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { DEFAULT_CONFIG, AGENTS_MD_CONTENT } from './types.js';
+const CONTEXT_DIR = '.context';
+const CONFIG_FILE = 'config.json';
+const AGENTS_FILE = 'agents.md';
+/**
+ * Load configuration from .context/config.json
+ */
+export async function loadConfig(workspaceRoot) {
+    const configPath = path.join(workspaceRoot, CONTEXT_DIR, CONFIG_FILE);
+    try {
+        const content = await fs.readFile(configPath, 'utf-8');
+        const config = JSON.parse(content);
+        return { ...DEFAULT_CONFIG, ...config };
+    }
+    catch (error) {
+        throw new Error(`Failed to load config. Run 'context-stash --init' first.`);
+    }
+}
+/**
+ * Save configuration to .context/config.json
+ */
+export async function saveConfig(workspaceRoot, config) {
+    const configPath = path.join(workspaceRoot, CONTEXT_DIR, CONFIG_FILE);
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+/**
+ * Initialize the context-stash workspace
+ */
+export async function initializeWorkspace(workspaceRoot) {
+    const contextDir = path.join(workspaceRoot, CONTEXT_DIR);
+    // Create .context directory
+    try {
+        await fs.mkdir(contextDir, { recursive: true });
+        console.log(`✓ Created ${CONTEXT_DIR}/ directory`);
+    }
+    catch (error) {
+        console.log(`✓ ${CONTEXT_DIR}/ directory already exists`);
+    }
+    // Create or update config.json
+    const configPath = path.join(contextDir, CONFIG_FILE);
+    try {
+        await fs.access(configPath);
+        console.log(`✓ ${CONTEXT_DIR}/${CONFIG_FILE} already exists`);
+    }
+    catch {
+        await saveConfig(workspaceRoot, DEFAULT_CONFIG);
+        console.log(`✓ Created ${CONTEXT_DIR}/${CONFIG_FILE}`);
+    }
+    // Create or update agents.md
+    const agentsPath = path.join(workspaceRoot, AGENTS_FILE);
+    try {
+        await fs.access(agentsPath);
+        console.log(`✓ ${AGENTS_FILE} already exists`);
+    }
+    catch {
+        await fs.writeFile(agentsPath, AGENTS_MD_CONTENT, 'utf-8');
+        console.log(`✓ Created ${AGENTS_FILE}`);
+    }
+    console.log('\n✓ Initialization complete!');
+    console.log(`\nTo use the MCP server, run:`);
+    console.log(`  context-stash --serve`);
+}
+/**
+ * Format index as filename according to config
+ */
+export function formatFilename(index, config) {
+    const paddedIndex = String(index).padStart(config.leadingZeros, '0');
+    return `${config.filePrefix}${paddedIndex}${config.fileSuffix}`;
+}
+/**
+ * Extract reference number from filename
+ */
+export function extractRef(filename, config) {
+    const { filePrefix, fileSuffix } = config;
+    if (!filename.startsWith(filePrefix) || !filename.endsWith(fileSuffix)) {
+        return null;
+    }
+    const start = filePrefix.length;
+    const end = filename.length - fileSuffix.length;
+    return filename.substring(start, end);
+}
+/**
+ * Get the next available index
+ */
+export async function getNextIndex(workspaceRoot, config) {
+    const contextDir = path.join(workspaceRoot, CONTEXT_DIR);
+    try {
+        const files = await fs.readdir(contextDir);
+        const indices = [];
+        for (const file of files) {
+            if (file === CONFIG_FILE)
+                continue;
+            const ref = extractRef(file, config);
+            if (ref) {
+                const index = parseInt(ref, 10);
+                if (!isNaN(index)) {
+                    indices.push(index);
+                }
+            }
+        }
+        if (indices.length === 0) {
+            return config.startIndex;
+        }
+        return Math.max(...indices) + 1;
+    }
+    catch (error) {
+        return config.startIndex;
+    }
+}
+/**
+ * Count lines in markdown content
+ */
+export function countLines(markdown) {
+    return markdown.split('\n').length;
+}
+/**
+ * Validate path to prevent directory traversal
+ */
+export function validatePath(requestedPath, workspaceRoot) {
+    const normalized = path.normalize(requestedPath);
+    const resolved = path.resolve(workspaceRoot, normalized);
+    if (!resolved.startsWith(workspaceRoot)) {
+        throw new Error('Path traversal detected');
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "context-stash",
+  "version": "1.0.0",
+  "description": "A workspace-scoped MCP server that provides a durable, Git-native memory layer for AI coding agents",
+  "main": "dist/index.js",
+  "bin": {
+    "context-stash": "dist/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc && node dist/cli.js",
+    "preview:site": "echo Open docs/index.html in your browser to preview the website"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "coding-agent",
+    "context",
+    "memory",
+    "documentation",
+    "git",
+    "claude",
+    "copilot",
+    "agent"
+  ],
+  "author": "Mark Taylor",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nzmarktaylor/context-stash.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nzmarktaylor/context-stash/issues"
+  },
+  "homepage": "https://github.com/nzmarktaylor/context-stash#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}