@borntorecycle/mcp-the-brain 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# MCP The Brain
+
+A Model Context Protocol (MCP) server for structured project memory — semantic search over outcomes, patterns, and module knowledge.
+
+## What It Does
+
+The Brain gives your AI coding assistant (Copilot, Claude, Cursor) access to structured project memory:
+- **Outcomes** — "X worked/failed because Y"
+- **Patterns** — "When doing A, prefer approach B"
+- **Module Knowledge** — "Module M is sensitive to N"
+
+Memory entries are stored as `.md` files in your repo (Git-versioned, diffable), with optional semantic search via Ollama embeddings + LanceDB.
+
+## Quick Setup
+
+### 1. Create `.brain.json` in your project root
+
+```json
+{
+  "schema": 1,
+  "projectName": "Your-Project",
+  "memoryRoot": "memories/project",
+  "sharedMemoryRoot": "~/.brain/shared",
+  "embedding": {
+    "provider": "ollama",
+    "model": "nomic-embed-text"
+  }
+}
+```
+
+### 2. Create memory directories
+
+```
+memories/project/outcomes/
+memories/project/patterns/
+memories/project/module-knowledge/
+```
+
+### 3. Add `.vscode/mcp.json`
+
+```json
+{
+  "servers": {
+    "the-brain": {
+      "command": "npx",
+      "args": ["-y", "@borntorecycle/mcp-the-brain"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+### 4. (Optional) Install Ollama for semantic search
+
+```
+ollama pull nomic-embed-text
+```
+
+Without Ollama, The Brain works in text-only mode.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `recall_knowledge` | Search memories by query, subsystem, tags, type |
+| `record_entry` | Create a new memory entry |
+| `update_entry` | Update or supersede an existing entry |
+| `list_by_subsystem` | List entries for a specific module |
+| `promote_to_shared` | Copy entry to cross-project shared memory |
+| `rebuild_index` | Regenerate index + embeddings from .md files |
+
+## License
+
+MIT

package/dist/bin/mcp-the-brain.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import '../src/server.js';
+//# sourceMappingURL=mcp-the-brain.d.ts.map

package/dist/bin/mcp-the-brain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-the-brain.d.ts","sourceRoot":"","sources":["../../bin/mcp-the-brain.ts"],"names":[],"mappings":";AACA,OAAO,kBAAkB,CAAC"}

package/dist/bin/mcp-the-brain.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import '../src/server.js';
+//# sourceMappingURL=mcp-the-brain.js.map

package/dist/bin/mcp-the-brain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-the-brain.js","sourceRoot":"","sources":["../../bin/mcp-the-brain.ts"],"names":[],"mappings":";AACA,OAAO,kBAAkB,CAAC"}

package/dist/src/config.d.ts

@@ -0,0 +1,15 @@
+import type { BrainConfig } from './types.js';
+/**
+ * Load and validate .brain.json from the given working directory.
+ * Throws with a clear message if the file is missing or invalid.
+ */
+export declare function loadConfig(cwd: string): BrainConfig;
+/**
+ * Resolve the absolute path for the project memory root.
+ */
+export declare function resolveMemoryRoot(cwd: string, config: BrainConfig): string;
+/**
+ * Resolve the absolute path for the shared memory root.
+ */
+export declare function resolveSharedRoot(config: BrainConfig): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/src/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAuB9C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAiDnD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAE1E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAE7D"}

package/dist/src/config.js

@@ -0,0 +1,83 @@
+// ─── .brain.json Configuration Reader ───
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { homedir } from 'node:os';
+const DEFAULT_CONFIG = {
+    schema: 1,
+    memoryRoot: 'memories/project',
+    sharedMemoryRoot: '~/.brain/shared',
+    embedding: {
+        provider: 'ollama',
+        model: 'nomic-embed-text',
+    },
+};
+/**
+ * Resolve ~ to the user's home directory.
+ */
+function expandTilde(p) {
+    if (p.startsWith('~/') || p.startsWith('~\\')) {
+        return join(homedir(), p.slice(2));
+    }
+    if (p === '~')
+        return homedir();
+    return p;
+}
+/**
+ * Load and validate .brain.json from the given working directory.
+ * Throws with a clear message if the file is missing or invalid.
+ */
+export function loadConfig(cwd) {
+    const configPath = resolve(cwd, '.brain.json');
+    if (!existsSync(configPath)) {
+        throw new Error(`No .brain.json found in ${cwd}. ` +
+            `Create a .brain.json file at the root of your project. ` +
+            `See https://github.com/HITM4N84/mcp-the-brain for setup instructions.`);
+    }
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf-8');
+    }
+    catch (err) {
+        throw new Error(`Failed to read .brain.json at ${configPath}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`.brain.json at ${configPath} is not valid JSON.`);
+    }
+    if (typeof parsed.projectName !== 'string' || parsed.projectName.length === 0) {
+        throw new Error(`.brain.json: "projectName" is required and must be a non-empty string.`);
+    }
+    const config = {
+        schema: typeof parsed.schema === 'number' ? parsed.schema : DEFAULT_CONFIG.schema,
+        projectName: parsed.projectName,
+        memoryRoot: typeof parsed.memoryRoot === 'string' ? parsed.memoryRoot : DEFAULT_CONFIG.memoryRoot,
+        sharedMemoryRoot: typeof parsed.sharedMemoryRoot === 'string'
+            ? parsed.sharedMemoryRoot
+            : DEFAULT_CONFIG.sharedMemoryRoot,
+        embedding: {
+            provider: typeof parsed.embedding?.provider === 'string'
+                ? parsed.embedding.provider
+                : DEFAULT_CONFIG.embedding.provider,
+            model: typeof parsed.embedding?.model === 'string'
+                ? parsed.embedding.model
+                : DEFAULT_CONFIG.embedding.model,
+        },
+    };
+    return config;
+}
+/**
+ * Resolve the absolute path for the project memory root.
+ */
+export function resolveMemoryRoot(cwd, config) {
+    return resolve(cwd, config.memoryRoot);
+}
+/**
+ * Resolve the absolute path for the shared memory root.
+ */
+export function resolveSharedRoot(config) {
+    return expandTilde(config.sharedMemoryRoot);
+}
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

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

package/dist/src/server.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/src/server.d.ts.map

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

package/dist/src/server.js

@@ -0,0 +1,161 @@
+// ─── MCP The Brain — Server Entry Point ───
+// A Model Context Protocol server for structured project memory.
+// Exposes 6 tools: recall_knowledge, record_entry, update_entry,
+// list_by_subsystem, promote_to_shared, rebuild_index.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { loadConfig, resolveMemoryRoot } from './config.js';
+import { recallKnowledge } from './tools/recallKnowledge.js';
+import { recordEntry } from './tools/recordEntry.js';
+import { updateEntry } from './tools/updateEntry.js';
+import { listBySubsystem } from './tools/listBySubsystem.js';
+import { promoteToShared } from './tools/promoteToShared.js';
+import { rebuildIndex } from './tools/rebuildIndex.js';
+import { checkDegradation } from './store/vectorStore.js';
+import { existsSync, mkdirSync } from 'node:fs';
+// ─── Configuration ───
+const cwd = process.cwd();
+let config;
+try {
+    config = loadConfig(cwd);
+}
+catch (err) {
+    // CRITICAL: For stdio MCP servers, NEVER write to stdout (corrupts JSON-RPC).
+    // All diagnostic output goes to stderr.
+    process.stderr.write(`FATAL: ${err.message}\n`);
+    process.exit(1);
+}
+// Ensure memory directories exist
+const memoryRoot = resolveMemoryRoot(cwd, config);
+if (!existsSync(memoryRoot)) {
+    mkdirSync(memoryRoot, { recursive: true });
+}
+// Check degradation status at startup
+const startupDegradation = await checkDegradation(config);
+if (startupDegradation.degraded) {
+    process.stderr.write(`⚠ The Brain starting in degraded mode: ${startupDegradation.reason}\n` +
+        `  Semantic search disabled. Text-only mode active.\n`);
+}
+else {
+    process.stderr.write(`✓ The Brain ready (project: ${config.projectName})\n`);
+}
+// ─── MCP Server ───
+const server = new McpServer({
+    name: 'the-brain',
+    version: '0.1.0',
+});
+// ─── Tool: recall_knowledge ───
+server.tool('recall_knowledge', 'Search project memory for relevant past outcomes, patterns, and module knowledge. ' +
+    'Uses semantic search when available, falls back to text matching.', {
+    query: z.string().describe('Natural language query to search memories for'),
+    subsystems: z.array(z.string()).optional().describe('Filter by module IDs (e.g., ["analyticalSimEngine"])'),
+    tags: z.array(z.string()).optional().describe('Filter by tags (e.g., ["calibration", "poisson"])'),
+    type: z.enum(['outcome', 'pattern', 'module-knowledge']).optional().describe('Filter by memory type'),
+    limit: z.number().min(1).max(20).optional().describe('Maximum results to return (default: 5)'),
+    scope: z.enum(['project', 'shared', 'all']).optional().describe('Search scope (default: "all" = project + shared)'),
+}, async (params) => {
+    const result = await recallKnowledge(cwd, config, params);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            }],
+    };
+});
+// ─── Tool: record_entry ───
+server.tool('record_entry', 'Create a new memory entry (outcome, pattern, or module-knowledge). ' +
+    'Writes a .md file, updates index.json, and generates embedding if Ollama is available.', {
+    type: z.enum(['outcome', 'pattern', 'module-knowledge']).describe('Memory entry type'),
+    title: z.string().describe('One-line summary of the knowledge'),
+    context: z.string().describe('What situation led to this knowledge'),
+    result: z.string().describe('What happened (success/failure/partial)'),
+    reason: z.string().describe('Root cause analysis'),
+    lesson: z.string().describe('Actionable takeaway for future decisions'),
+    action: z.string().describe('What was done as a result'),
+    subsystems: z.array(z.string()).describe('Module IDs from INDEX_Project.md'),
+    tags: z.array(z.string()).describe('Free-form searchable tags'),
+    relatedAdrs: z.array(z.string()).optional().describe('Back-references to ADR identifiers'),
+    confidence: z.enum(['high', 'medium', 'low']).optional().describe('Confidence level (default: medium)'),
+}, async (params) => {
+    const result = await recordEntry(cwd, config, params);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            }],
+    };
+});
+// ─── Tool: update_entry ───
+server.tool('update_entry', 'Update an existing memory entry. Can modify body fields, status, confidence, tags, etc. ' +
+    'Setting status to "superseded" requires providing superseded-by ID.', {
+    id: z.string().describe('ID of the entry to update (e.g., "OUT-2026-0315-001")'),
+    updates: z.object({
+        title: z.string().optional(),
+        context: z.string().optional(),
+        result: z.string().optional(),
+        reason: z.string().optional(),
+        lesson: z.string().optional(),
+        action: z.string().optional(),
+        status: z.enum(['validated', 'superseded', 'uncertain', 'deprecated']).optional(),
+        confidence: z.enum(['high', 'medium', 'low']).optional(),
+        tags: z.array(z.string()).optional(),
+        subsystems: z.array(z.string()).optional(),
+        'superseded-by': z.string().optional(),
+    }).describe('Fields to update'),
+}, async (params) => {
+    const result = await updateEntry(cwd, config, params);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            }],
+    };
+});
+// ─── Tool: list_by_subsystem ───
+server.tool('list_by_subsystem', 'List all memory entries that reference a given module/subsystem ID. Fast path via index.json.', {
+    subsystem: z.string().describe('Module ID to filter by (e.g., "analyticalSimEngine", "optimizer")'),
+    scope: z.enum(['project', 'shared', 'all']).optional().describe('Search scope (default: "all")'),
+}, (params) => {
+    const result = listBySubsystem(cwd, config, params);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            }],
+    };
+});
+// ─── Tool: promote_to_shared ───
+server.tool('promote_to_shared', 'Copy a project memory entry to shared cross-project memory (~/.brain/shared/). ' +
+    'The original project entry is NOT deleted.', {
+    id: z.string().describe('ID of the project entry to promote'),
+    removeProjectSpecific: z.array(z.string()).optional()
+        .describe('Fields to clear when promoting (e.g., ["subsystems"] for project-specific module IDs)'),
+}, async (params) => {
+    const result = await promoteToShared(cwd, config, params);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            }],
+    };
+});
+// ─── Tool: rebuild_index ───
+server.tool('rebuild_index', 'Regenerate index.json and vector embeddings from all .md memory files. ' +
+    'Idempotent — safe to run at any time.', {
+    scope: z.enum(['project', 'shared', 'all']).optional()
+        .describe('Which indexes to rebuild (default: "all")'),
+}, async (params) => {
+    const result = await rebuildIndex(cwd, config, params);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            }],
+    };
+});
+// ─── Start stdio transport ───
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(`✓ The Brain MCP server connected (stdio)\n`);
+//# sourceMappingURL=server.js.map

package/dist/src/server.js.map

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

package/dist/src/store/indexStore.d.ts

@@ -0,0 +1,20 @@
+import type { IndexEntry, MemoryEntry } from '../types.js';
+/**
+ * Read index.json from a memory root.
+ * Returns empty array if file doesn't exist.
+ */
+export declare function readIndex(memoryRoot: string): IndexEntry[];
+/**
+ * Write index.json to a memory root.
+ * Entries are sorted by date (newest first).
+ */
+export declare function writeIndex(memoryRoot: string, entries: IndexEntry[]): void;
+/**
+ * Convert a MemoryEntry to an IndexEntry.
+ */
+export declare function entryToIndexEntry(entry: MemoryEntry, relativeFile: string): IndexEntry;
+/**
+ * Add or update a single entry in the index.
+ */
+export declare function upsertIndexEntry(memoryRoot: string, indexEntry: IndexEntry): void;
+//# sourceMappingURL=indexStore.d.ts.map

package/dist/src/store/indexStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexStore.d.ts","sourceRoot":"","sources":["../../../src/store/indexStore.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE3D;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,EAAE,CAc1D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI,CAO1E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,GAAG,UAAU,CAatF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,CAWjF"}

package/dist/src/store/indexStore.js

@@ -0,0 +1,63 @@
+// ─── Index Store: Read/Write index.json for fast metadata lookups ───
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Read index.json from a memory root.
+ * Returns empty array if file doesn't exist.
+ */
+export function readIndex(memoryRoot) {
+    const indexPath = join(memoryRoot, 'index.json');
+    if (!existsSync(indexPath)) {
+        return [];
+    }
+    try {
+        const raw = readFileSync(indexPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        process.stderr.write(`⚠ Failed to read index.json: ${err.message}\n`);
+        return [];
+    }
+}
+/**
+ * Write index.json to a memory root.
+ * Entries are sorted by date (newest first).
+ */
+export function writeIndex(memoryRoot, entries) {
+    const indexPath = join(memoryRoot, 'index.json');
+    // Sort by date descending
+    const sorted = [...entries].sort((a, b) => b.date.localeCompare(a.date));
+    writeFileSync(indexPath, JSON.stringify(sorted, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Convert a MemoryEntry to an IndexEntry.
+ */
+export function entryToIndexEntry(entry, relativeFile) {
+    return {
+        id: entry.frontmatter.id,
+        type: entry.frontmatter.type,
+        file: relativeFile,
+        title: entry.body.title,
+        date: entry.frontmatter.date,
+        subsystems: entry.frontmatter.subsystems,
+        tags: entry.frontmatter.tags,
+        relatedAdrs: entry.frontmatter['related-adrs'],
+        status: entry.frontmatter.status,
+        confidence: entry.frontmatter.confidence,
+    };
+}
+/**
+ * Add or update a single entry in the index.
+ */
+export function upsertIndexEntry(memoryRoot, indexEntry) {
+    const entries = readIndex(memoryRoot);
+    const existing = entries.findIndex(e => e.id === indexEntry.id);
+    if (existing >= 0) {
+        entries[existing] = indexEntry;
+    }
+    else {
+        entries.push(indexEntry);
+    }
+    writeIndex(memoryRoot, entries);
+}
+//# sourceMappingURL=indexStore.js.map

package/dist/src/store/indexStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexStore.js","sourceRoot":"","sources":["../../../src/store/indexStore.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAEvE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,UAAkB;IAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IAEjD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiB,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAiC,GAAa,CAAC,OAAO,IAAI,CAAC,CAAC;QACjF,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,UAAkB,EAAE,OAAqB;IAClE,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IAEjD,0BAA0B;IAC1B,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAEzE,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAkB,EAAE,YAAoB;IACxE,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,WAAW,CAAC,EAAE;QACxB,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI;QAC5B,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK;QACvB,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI;QAC5B,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,UAAU;QACxC,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI;QAC5B,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,cAAc,CAAC;QAC9C,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,MAAM;QAChC,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,UAAU;KACzC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,UAAsB;IACzE,MAAM,OAAO,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,UAAU,CAAC,EAAE,CAAC,CAAC;IAEhE,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAClB,OAAO,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC;IACjC,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC3B,CAAC;IAED,UAAU,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAClC,CAAC"}

package/dist/src/store/markdownStore.d.ts

@@ -0,0 +1,27 @@
+import type { MemoryEntry, MemoryFrontmatter, MemoryBody } from '../types.js';
+/**
+ * Read a single memory entry from a .md file.
+ */
+export declare function readEntry(filePath: string, source: 'project' | 'shared'): MemoryEntry;
+/**
+ * Read all memory entries from a memory root directory.
+ */
+export declare function readAllEntries(memoryRoot: string, source: 'project' | 'shared'): MemoryEntry[];
+/**
+ * Write a new memory entry as a .md file.
+ * Returns the relative file path within the memory root.
+ */
+export declare function writeEntry(memoryRoot: string, frontmatter: MemoryFrontmatter, body: MemoryBody): string;
+/**
+ * Update an existing memory entry's frontmatter and/or body.
+ */
+export declare function updateEntryFile(memoryRoot: string, id: string, updates: Partial<MemoryFrontmatter & MemoryBody>): void;
+/**
+ * Find an entry by ID across the type directories.
+ */
+export declare function findEntryById(memoryRoot: string, id: string, source: 'project' | 'shared'): MemoryEntry | null;
+/**
+ * Get the relative file path for an entry within the memory root.
+ */
+export declare function getEntryRelativePath(memoryRoot: string, entry: MemoryEntry): string;
+//# sourceMappingURL=markdownStore.d.ts.map

package/dist/src/store/markdownStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownStore.d.ts","sourceRoot":"","sources":["../../../src/store/markdownStore.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,UAAU,EAAc,MAAM,aAAa,CAAC;AAgC1F;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,CAarF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,EAAE,CAmB9F;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,iBAAiB,EAC9B,IAAI,EAAE,UAAU,GACf,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,CAAC,iBAAiB,GAAG,UAAU,CAAC,GAC/C,IAAI,CAiBN;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,SAAS,GAAG,QAAQ,GAC3B,WAAW,GAAG,IAAI,CAQpB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAEnF"}