@scitrera/memorylayer-mcp-server 0.0.3

package/README.md

@@ -0,0 +1,350 @@
+# @scitrera/memorylayer-mcp-server
+
+TypeScript MCP (Model Context Protocol) server for [MemoryLayer.ai](https://memorylayer.ai).
+
+Provides 16 memory tools for LLM agents to store, recall, synthesize, and manage information across sessions.
+
+## Installation
+
+```bash
+npm install @scitrera/memorylayer-mcp-server
+```
+
+## Quick Start
+
+### As a Standalone MCP Server
+
+```bash
+# Set environment variables
+export MEMORYLAYER_URL=http://localhost:61001
+export MEMORYLAYER_WORKSPACE_ID=my-workspace
+
+# Run the server
+npx memorylayer-mcp
+```
+
+### Claude Code Configuration (Recommended)
+
+> **Detailed setup guide:** See [CLAUDE_CODE_SETUP.md](../docs/CLAUDE_CODE_SETUP.md) for step-by-step instructions.
+
+Claude Code runs MCP servers from the project directory, so our server auto-detects the workspace from your git repo or folder name. Add `.mcp.json` to your project root:
+
+```json
+{
+  "mcpServers": {
+    "memorylayer": {
+      "command": "npx",
+      "args": ["@scitrera/memorylayer-mcp-server"],
+      "env": {
+        "MEMORYLAYER_URL": "http://localhost:61001"
+      }
+    }
+  }
+}
+```
+
+**Auto-workspace detection**: The server uses your git repo name (or directory name) as the workspace ID. Each project gets isolated memory storage automatically.
+
+**Override options:**
+```json
+{
+  "mcpServers": {
+    "memorylayer": {
+      "command": "npx",
+      "args": ["@scitrera/memorylayer-mcp-server"],
+      "env": {
+        "MEMORYLAYER_URL": "http://localhost:61001",
+        "MEMORYLAYER_WORKSPACE_ID": "${WORKSPACE_ID:-my-project}"
+      }
+    }
+  }
+}
+```
+
+Or via CLI:
+```bash
+claude mcp add --transport stdio memorylayer \
+  --env MEMORYLAYER_URL=http://localhost:61001 \
+  -- npx @scitrera/memorylayer-mcp-server
+```
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "memorylayer": {
+      "command": "npx",
+      "args": ["@scitrera/memorylayer-mcp-server"],
+      "env": {
+        "MEMORYLAYER_URL": "http://localhost:61001",
+        "MEMORYLAYER_WORKSPACE_ID": "my-project"
+      }
+    }
+  }
+}
+```
+
+**Note**: Claude Desktop doesn't change directories per-project, so you should set `MEMORYLAYER_WORKSPACE_ID` explicitly for each project entry.
+
+### Programmatic Usage
+
+```typescript
+import { MemoryLayerClient, createServer } from "@scitrera/memorylayer-mcp-server";
+
+// Create client (wraps the @scitrera/memorylayer-sdk)
+const client = new MemoryLayerClient({
+  baseUrl: "http://localhost:61001",
+  workspaceId: "my-workspace",
+  apiKey: "optional-api-key"
+});
+
+// Create MCP server
+const server = await createServer(client);
+
+// Run server on stdio transport
+await server.run();
+```
+
+## Available Tools
+
+### Core Memory Tools (5)
+
+#### 1. `memory_remember`
+Store a new memory for later recall.
+
+```typescript
+{
+  content: "User prefers TypeScript for new projects",
+  type: "semantic",        // episodic, semantic, procedural, working
+  importance: 0.8,         // 0.0 - 1.0
+  tags: ["preference", "typescript"],
+  subtype: "Preference"    // Optional domain classification
+}
+```
+
+#### 2. `memory_recall`
+Search memories by semantic query.
+
+```typescript
+{
+  query: "What are the user's coding preferences?",
+  limit: 10,
+  min_relevance: 0.5,
+  types: ["semantic"],     // Optional filter
+  tags: ["preference"]     // Optional filter (AND logic)
+}
+```
+
+#### 3. `memory_reflect`
+Synthesize insights across multiple memories.
+
+```typescript
+{
+  query: "What patterns have we seen with database performance?",
+  max_tokens: 500,
+  include_sources: true,
+  depth: 2                // Association traversal depth
+}
+```
+
+#### 4. `memory_forget`
+Delete or decay outdated information.
+
+```typescript
+{
+  memory_id: "mem_abc123",
+  reason: "Outdated information",
+  hard: false             // true = permanent delete
+}
+```
+
+#### 5. `memory_associate`
+Link memories with typed relationships.
+
+```typescript
+{
+  source_id: "mem_problem",
+  target_id: "mem_solution",
+  relationship: "solves",  // 60+ relationship types available
+  strength: 0.9           // 0.0 - 1.0
+}
+```
+
+### Extended Memory Tools (4)
+
+#### 6. `memory_briefing`
+Get a session briefing with recent context.
+
+```typescript
+{
+  lookback_hours: 24,
+  include_contradictions: true
+}
+```
+
+#### 7. `memory_statistics`
+Get workspace analytics and memory usage.
+
+```typescript
+{
+  include_breakdown: true  // Include breakdown by type/subtype
+}
+```
+
+#### 8. `memory_graph_query`
+Multi-hop graph traversal for causal chains.
+
+```typescript
+{
+  start_memory_id: "mem_abc123",
+  relationship_types: ["causes", "triggers"],
+  max_depth: 3,
+  direction: "both",      // outgoing, incoming, both
+  max_paths: 50
+}
+```
+
+#### 9. `memory_audit`
+Find contradictions and inconsistencies.
+
+```typescript
+{
+  memory_id: "mem_abc123",  // Optional - omit to audit entire workspace
+  auto_resolve: false       // Auto-prefer newer contradicting memories
+}
+```
+
+### Session Management Tools (3)
+
+These tools enable working memory that persists across tool calls within a session.
+
+#### 10. `memory_session_start`
+Start a new session for working memory tracking.
+
+```typescript
+{
+  metadata: { task: "debugging" }  // Optional metadata
+}
+```
+
+#### 11. `memory_session_end`
+End the current session and optionally commit working memory.
+
+```typescript
+{
+  commit: true,               // Commit to long-term storage
+  importance_threshold: 0.5   // Min importance for extracted memories
+}
+```
+
+#### 12. `memory_session_status`
+Get current session status including working memory summary.
+
+```typescript
+{}  // No parameters required
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MEMORYLAYER_URL` | Base URL for MemoryLayer API | `http://localhost:61001` |
+| `MEMORYLAYER_API_KEY` | API key for authentication | (none) |
+| `MEMORYLAYER_WORKSPACE_ID` | Workspace ID (overrides auto-detection) | (auto-detected) |
+| `MEMORYLAYER_AUTO_WORKSPACE` | Set to `false` to disable auto-detection | `true` |
+
+## Memory Types
+
+- **Episodic**: Specific events/interactions
+- **Semantic**: Facts, concepts, relationships
+- **Procedural**: How-to knowledge
+- **Working**: Current task context (session-scoped)
+
+## Relationship Types (60+)
+
+Organized into 11 categories:
+
+**Hierarchical**: parent_of, child_of, part_of, contains, instance_of, subtype_of
+**Causal**: causes, triggers, leads_to, prevents
+**Temporal**: precedes, concurrent_with, follows_temporally
+**Similarity**: similar_to, variant_of, related_to
+**Learning**: builds_on, contradicts, confirms, supersedes
+**Refinement**: refines, abstracts, specializes, generalizes
+**Reference**: references, referenced_by
+**Solution**: solves, addresses, alternative_to, improves
+**Context**: occurs_in, applies_to, works_with, requires
+**Workflow**: follows, depends_on, enables, blocks
+**Quality**: effective_for, preferred_over, deprecated_by
+
+## Architecture
+
+The MCP server wraps the `@scitrera/memorylayer-sdk` TypeScript SDK, providing an MCP-compatible interface for LLM agents.
+
+```
+memorylayer-mcp-typescript/
+├── src/
+│   ├── types.ts       # TypeScript types for MCP tools
+│   ├── tools.ts       # MCP tool definitions (12 tools)
+│   ├── client.ts      # Wrapper around @scitrera/memorylayer-sdk
+│   ├── session.ts     # Local session state management
+│   ├── handlers.ts    # Tool handler implementations
+│   ├── server.ts      # MCP server using @modelcontextprotocol/sdk
+│   └── index.ts       # Main exports
+├── bin/
+│   └── memorylayer-mcp.ts  # CLI entry point
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Run locally
+npm start
+```
+
+## Using the SDK Client Directly
+
+The MCP server's client is a thin wrapper around the TypeScript SDK. For direct SDK usage without MCP, install `@scitrera/memorylayer-sdk`:
+
+```bash
+npm install @scitrera/memorylayer-sdk
+```
+
+```typescript
+import { MemoryLayerClient } from "@scitrera/memorylayer-sdk";
+
+const client = new MemoryLayerClient({
+  baseUrl: "http://localhost:61001",
+  workspaceId: "my-workspace"
+});
+
+const memory = await client.remember("Important fact", {
+  type: "semantic",
+  importance: 0.8
+});
+```
+
+## License
+
+Apache 2.0 License - see LICENSE file for details.
+
+## Links
+
+- [MemoryLayer.ai](https://memorylayer.ai)
+- [Documentation](https://docs.memorylayer.ai)
+- [TypeScript SDK](https://www.npmjs.com/package/@scitrera/memorylayer-sdk)
+- [Model Context Protocol](https://modelcontextprotocol.io)

package/dist/bin/memorylayer-hook.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for MemoryLayer Claude Code hooks
+ *
+ * Usage:
+ *   memorylayer-hook <hook-type>
+ *
+ * Reads HookInput JSON from stdin, writes HookOutput JSON to stdout.
+ *
+ * Hook types:
+ *   SessionStart     - Called at session start
+ *   UserPromptSubmit - Called when user submits a prompt
+ *   PreToolUse       - Called before a tool is used
+ *   PostToolUse      - Called after a tool is used
+ *   PreCompact       - Called before context compaction
+ *   Stop             - Called when session ends
+ */
+export {};
+//# sourceMappingURL=memorylayer-hook.d.ts.map

package/dist/bin/memorylayer-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memorylayer-hook.d.ts","sourceRoot":"","sources":["../../bin/memorylayer-hook.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG"}

package/dist/bin/memorylayer-hook.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for MemoryLayer Claude Code hooks
+ *
+ * Usage:
+ *   memorylayer-hook <hook-type>
+ *
+ * Reads HookInput JSON from stdin, writes HookOutput JSON to stdout.
+ *
+ * Hook types:
+ *   SessionStart     - Called at session start
+ *   UserPromptSubmit - Called when user submits a prompt
+ *   PreToolUse       - Called before a tool is used
+ *   PostToolUse      - Called after a tool is used
+ *   PreCompact       - Called before context compaction
+ *   Stop             - Called when session ends
+ */
+import { appendFileSync } from "fs";
+import { HookEvent } from "../src/hooks/types.js";
+import { handleSessionStart } from "../src/hooks/handlers/session-start.js";
+import { handleUserPromptSubmit } from "../src/hooks/handlers/user-prompt.js";
+import { handlePreToolUse } from "../src/hooks/handlers/pre-tool.js";
+import { handlePostToolUse } from "../src/hooks/handlers/post-tool.js";
+import { handleStop } from "../src/hooks/handlers/stop.js";
+import { resetRecallStatus, updateSessionInfo } from "../src/hooks/state.js";
+import { getClient } from "../src/hooks/client.js";
+/**
+ * Read all input from stdin
+ */
+async function readStdin() {
+    const chunks = [];
+    return new Promise((resolve, reject) => {
+        process.stdin.on("data", (chunk) => chunks.push(chunk));
+        process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        process.stdin.on("error", reject);
+        // Timeout after 5 seconds if no input
+        setTimeout(() => {
+            if (chunks.length === 0) {
+                resolve("{}");
+            }
+        }, 5000);
+    });
+}
+/**
+ * Parse hook type from command line
+ */
+function parseHookType(arg) {
+    if (!arg)
+        return null;
+    const normalized = arg.toLowerCase();
+    switch (normalized) {
+        case "sessionstart":
+            return HookEvent.SessionStart;
+        case "userpromptsubmit":
+            return HookEvent.UserPromptSubmit;
+        case "pretooluse":
+            return HookEvent.PreToolUse;
+        case "posttooluse":
+            return HookEvent.PostToolUse;
+        case "precompact":
+            return HookEvent.PreCompact;
+        case "stop":
+            return HookEvent.Stop;
+        default:
+            return null;
+    }
+}
+/** Hooks that support hookSpecificOutput with additionalContext */
+const HOOKS_WITH_ADDITIONAL_CONTEXT = new Set([
+    HookEvent.SessionStart, // Works empirically even though not in schema
+    HookEvent.PreToolUse,
+    HookEvent.PostToolUse,
+    HookEvent.UserPromptSubmit,
+]);
+/**
+ * Build properly formatted hook output
+ */
+function buildOutput(hookType, additionalContext, block = false, reason) {
+    const output = {
+        continue: !block, // Always continue unless blocking
+    };
+    // For PreToolUse, we can block
+    if (hookType === HookEvent.PreToolUse && block) {
+        output.continue = false;
+        output.decision = "block";
+        output.reason = reason || "Blocked by MemoryLayer hook";
+    }
+    // Only add hookSpecificOutput for hooks that support it
+    // SessionStart, Stop, PreCompact do NOT support hookSpecificOutput
+    if (additionalContext && HOOKS_WITH_ADDITIONAL_CONTEXT.has(hookType)) {
+        output.hookSpecificOutput = {
+            hookEventName: hookType,
+            additionalContext,
+        };
+    }
+    return output;
+}
+/**
+ * Build error output
+ */
+function buildErrorOutput(hookType, error) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: hookType,
+            additionalContext: `MemoryLayer hook error: ${error}`,
+        },
+    };
+}
+/**
+ * Convert legacy HookOutput to HandlerResult
+ */
+function legacyToResult(output) {
+    // Handle new format (has hookSpecificOutput)
+    if (output.hookSpecificOutput) {
+        return {
+            additionalContext: output.hookSpecificOutput.additionalContext,
+            block: output.decision === "block",
+            reason: output.reason,
+        };
+    }
+    // Handle legacy format (has additionalContext at top level)
+    return {
+        additionalContext: output.additionalContext,
+        block: output.block,
+        reason: output.blockReason,
+        error: output.error,
+    };
+}
+/**
+ * Dispatch to appropriate handler
+ */
+async function dispatch(hookType, input) {
+    switch (hookType) {
+        case HookEvent.SessionStart: {
+            // Reset recall status at session start
+            resetRecallStatus();
+            // Write workspace ID and session ID to CLAUDE_ENV_FILE for subsequent bash commands
+            const envFile = process.env.CLAUDE_ENV_FILE;
+            if (envFile) {
+                try {
+                    const client = getClient();
+                    const workspaceId = client.getWorkspaceId();
+                    appendFileSync(envFile, `export MEMORYLAYER_WORKSPACE_ID="${workspaceId}"\n`);
+                    // Start a server-side session and export its ID
+                    const sessionResult = await client.startSession({ ttl_seconds: 3600 });
+                    appendFileSync(envFile, `export MEMORYLAYER_SESSION_ID="${sessionResult.session_id}"\n`);
+                    // Also save to hook state so the Stop handler can access it
+                    updateSessionInfo(workspaceId, sessionResult.session_id);
+                }
+                catch {
+                    // Ignore errors - memory features will still work via MCP tools
+                }
+            }
+            return legacyToResult(await handleSessionStart(input));
+        }
+        case HookEvent.UserPromptSubmit:
+            // Reset recall status for new user turn
+            resetRecallStatus();
+            return legacyToResult(await handleUserPromptSubmit(input));
+        case HookEvent.PreToolUse:
+            return legacyToResult(await handlePreToolUse(input));
+        case HookEvent.PostToolUse:
+            return legacyToResult(await handlePostToolUse(input));
+        case HookEvent.PreCompact:
+            // PreCompact: Can't inject instructions at this point, just continue
+            return {};
+        case HookEvent.Stop:
+            // Stop: commit working memory and end session (side effects only, no context injection)
+            return legacyToResult(await handleStop());
+        default:
+            return {};
+    }
+}
+/**
+ * Main entry point
+ */
+async function main() {
+    const hookTypeArg = process.argv[2];
+    const hookType = parseHookType(hookTypeArg);
+    if (!hookType) {
+        const output = {
+            error: `Invalid or missing hook type. Usage: memorylayer-hook <hook-type>\nValid types: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop`,
+        };
+        console.log(JSON.stringify(output));
+        process.exit(1);
+    }
+    try {
+        // Read input from stdin
+        const stdinData = await readStdin();
+        let input;
+        try {
+            input = stdinData.trim() ? JSON.parse(stdinData) : { hook_type: hookType };
+        }
+        catch {
+            input = { hook_type: hookType };
+        }
+        // Add hook type to input
+        input.hook_type = hookType;
+        // Dispatch to handler
+        const result = await dispatch(hookType, input);
+        // Handle errors from handlers
+        if (result.error) {
+            const output = buildErrorOutput(hookType, result.error);
+            console.log(JSON.stringify(output));
+            return;
+        }
+        // Build properly formatted output
+        const output = buildOutput(hookType, result.additionalContext, result.block, result.reason);
+        // Write output to stdout
+        console.log(JSON.stringify(output));
+    }
+    catch (error) {
+        const output = buildErrorOutput(hookType, error instanceof Error ? error.message : String(error));
+        console.log(JSON.stringify(output));
+        process.exit(1);
+    }
+}
+// Run
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=memorylayer-hook.js.map

package/dist/bin/memorylayer-hook.js.map

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

package/dist/bin/memorylayer-mcp.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for MemoryLayer MCP server
+ *
+ * Usage:
+ *   memorylayer-mcp
+ *
+ * Environment variables:
+ *   MEMORYLAYER_URL - Base URL for MemoryLayer API (default: http://localhost:61001)
+ *   MEMORYLAYER_API_KEY - API key for authentication (optional)
+ *   MEMORYLAYER_WORKSPACE_ID - Workspace ID (default: auto-detected from directory)
+ *   MEMORYLAYER_AUTO_WORKSPACE - Set to "false" to disable auto-detection
+ *   MEMORYLAYER_SESSION_MODE - Set to "false" to disable session/working memory (default: true)
+ */
+export {};
+//# sourceMappingURL=memorylayer-mcp.d.ts.map

package/dist/bin/memorylayer-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memorylayer-mcp.d.ts","sourceRoot":"","sources":["../../bin/memorylayer-mcp.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}

package/dist/bin/memorylayer-mcp.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for MemoryLayer MCP server
+ *
+ * Usage:
+ *   memorylayer-mcp
+ *
+ * Environment variables:
+ *   MEMORYLAYER_URL - Base URL for MemoryLayer API (default: http://localhost:61001)
+ *   MEMORYLAYER_API_KEY - API key for authentication (optional)
+ *   MEMORYLAYER_WORKSPACE_ID - Workspace ID (default: auto-detected from directory)
+ *   MEMORYLAYER_AUTO_WORKSPACE - Set to "false" to disable auto-detection
+ *   MEMORYLAYER_SESSION_MODE - Set to "false" to disable session/working memory (default: true)
+ */
+import { MemoryLayerClient } from "../src/client.js";
+import { createServer } from "../src/server.js";
+import { detectWorkspaceId } from "../src/workspace.js";
+async function main() {
+    // Parse environment variables
+    const baseUrl = process.env.MEMORYLAYER_URL || "http://localhost:61001";
+    const apiKey = process.env.MEMORYLAYER_API_KEY;
+    const autoWorkspace = process.env.MEMORYLAYER_AUTO_WORKSPACE !== "false";
+    const sessionMode = process.env.MEMORYLAYER_SESSION_MODE !== "false";
+    // Log working directory for debugging workspace detection issues
+    console.error(`MCP server starting in directory: ${process.cwd()}`);
+    // Determine workspace ID
+    let workspaceId;
+    if (process.env.MEMORYLAYER_WORKSPACE_ID) {
+        workspaceId = process.env.MEMORYLAYER_WORKSPACE_ID;
+        console.error(`Using explicit workspace from env: ${workspaceId}`);
+    }
+    else if (autoWorkspace) {
+        workspaceId = detectWorkspaceId();
+        console.error(`Auto-detected workspace: ${workspaceId}`);
+    }
+    else {
+        workspaceId = "default";
+        console.error(`Using default workspace: ${workspaceId}`);
+    }
+    // Create client
+    const client = new MemoryLayerClient({
+        baseUrl,
+        apiKey,
+        workspaceId
+    });
+    // Create and run server
+    const server = await createServer(client, { workspaceId, sessionMode });
+    console.error("MemoryLayer MCP Server Manifest:", JSON.stringify(server.getManifest(), null, 2));
+    await server.run();
+}
+// Handle errors and signals
+process.on("SIGINT", () => {
+    console.error("Received SIGINT, shutting down gracefully");
+    process.exit(0);
+});
+process.on("SIGTERM", () => {
+    console.error("Received SIGTERM, shutting down gracefully");
+    process.exit(0);
+});
+process.on("uncaughtException", (error) => {
+    console.error("Uncaught exception:", error);
+    process.exit(1);
+});
+process.on("unhandledRejection", (reason) => {
+    console.error("Unhandled rejection:", reason);
+    process.exit(1);
+});
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=memorylayer-mcp.js.map

package/dist/bin/memorylayer-mcp.js.map

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

package/examples/client-usage.ts

@@ -0,0 +1,93 @@
+/**
+ * Example usage of the MemoryLayer client
+ */
+
+// @ts-ignore
+import { MemoryLayerClient, MemoryType, RelationshipType } from "@scitrera/memorylayer-mcp-server";
+
+async function main() {
+  // Create client instance
+  const client = new MemoryLayerClient({
+    baseUrl: "http://localhost:61001",
+    workspaceId: "example-workspace"
+  });
+
+  // 1. Store some memories
+  console.log("1. Storing memories...");
+
+  const problemMemory = await client.remember({
+    content: "User encountered authentication timeout errors when API response takes >30s",
+    type: MemoryType.EPISODIC,
+    importance: 0.7,
+    tags: ["authentication", "timeout", "problem"]
+  });
+  console.log(`Stored problem memory: ${problemMemory.id}`);
+
+  const solutionMemory = await client.remember({
+    content: "Increased authentication timeout to 60s and added retry logic with exponential backoff",
+    type: MemoryType.PROCEDURAL,
+    importance: 0.9,
+    tags: ["authentication", "timeout", "solution"]
+  });
+  console.log(`Stored solution memory: ${solutionMemory.id}`);
+
+  // 2. Create an association between problem and solution
+  console.log("\n2. Creating association...");
+
+  const association = await client.associate({
+    source_id: solutionMemory.id,
+    target_id: problemMemory.id,
+    relationship: RelationshipType.SOLVES,
+    strength: 0.95
+  });
+  console.log(`Created association: ${association.id}`);
+
+  // 3. Recall memories about authentication
+  console.log("\n3. Recalling memories about authentication...");
+
+  const recallResult = await client.recall({
+    query: "authentication timeout issues",
+    limit: 5,
+    min_relevance: 0.5
+  });
+
+  console.log(`Found ${recallResult.memories.length} memories:`);
+  for (const memory of recallResult.memories) {
+    console.log(`  - [${memory.type}] ${memory.content.substring(0, 80)}...`);
+  }
+
+  // 4. Reflect on authentication patterns
+  console.log("\n4. Reflecting on authentication patterns...");
+
+  const reflectResult = await client.reflect({
+    query: "What have we learned about handling authentication timeouts?",
+    max_tokens: 300,
+    include_sources: true
+  });
+
+  console.log("Reflection:");
+  console.log(reflectResult.reflection);
+  console.log(`\nBased on ${reflectResult.source_memories.length} source memories`);
+
+  // 5. Get workspace statistics
+  console.log("\n5. Getting workspace statistics...");
+
+  const stats = await client.getStatistics(true);
+  console.log(`Total memories: ${stats.total_memories}`);
+  console.log(`Total associations: ${stats.total_associations}`);
+
+  if (stats.breakdown) {
+    console.log("\nMemories by type:");
+    for (const [type, count] of Object.entries(stats.breakdown.by_type)) {
+      console.log(`  ${type}: ${count}`);
+    }
+  }
+
+  // 6. Get a briefing
+  console.log("\n6. Getting session briefing...");
+
+  const briefing = await client.getBriefing(24, true);
+  console.log(briefing.briefing);
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@scitrera/memorylayer-mcp-server",
+  "version": "0.0.3",
+  "description": "MCP (Model Context Protocol) server for MemoryLayer.ai",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "memorylayer-mcp": "dist/bin/memorylayer-mcp.js",
+    "memorylayer-hook": "dist/bin/memorylayer-hook.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/bin/memorylayer-mcp.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "ai",
+    "llm",
+    "agent"
+  ],
+  "author": "Scitrera LLC <> (https://scitrera.ai)",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@scitrera/memorylayer-sdk": "^0.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scitrera/memorylayer"
+  }
+}

package/tests/server.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Tests for MCP Server
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { MCPServer, createServer } from "../src/server.js";
+import { MemoryLayerClient } from "../src/client.js";
+import { TOOLS, SESSION_TOOLS, CONTEXT_ENVIRONMENT_TOOLS } from "../src/tools.js";
+
+// Mock the SDK client
+vi.mock("../src/client.js", () => {
+  return {
+    MemoryLayerClient: vi.fn().mockImplementation(() => ({
+      getWorkspaceId: vi.fn().mockReturnValue("test-workspace"),
+      remember: vi.fn().mockResolvedValue({ id: "mem-123", type: "semantic", importance: 0.5, tags: [] }),
+      recall: vi.fn().mockResolvedValue({ memories: [], total_count: 0, search_latency_ms: 10, mode_used: "semantic" }),
+      startSession: vi.fn().mockResolvedValue({ session_id: "server-session-123" }),
+      endSession: vi.fn().mockResolvedValue({ memories_extracted: 2 }),
+    })),
+  };
+});
+
+describe("MCPServer", () => {
+  let client: MemoryLayerClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new MemoryLayerClient({ baseUrl: "http://localhost:61001" });
+  });
+
+  describe("constructor", () => {
+    it("should create server with default options", () => {
+      const server = new MCPServer(client);
+      expect(server).toBeDefined();
+    });
+
+    it("should enable session mode by default", () => {
+      const server = new MCPServer(client);
+      const manifest = server.getManifest();
+      expect(manifest.name).toBe("memorylayer");
+    });
+
+    it("should accept custom options", () => {
+      const server = new MCPServer(client, {
+        workspaceId: "custom-workspace",
+        sessionMode: false,
+      });
+      expect(server).toBeDefined();
+    });
+  });
+
+  describe("getManifest", () => {
+    it("should return server manifest", () => {
+      const server = new MCPServer(client);
+      const manifest = server.getManifest();
+
+      expect(manifest.name).toBe("memorylayer");
+      expect(manifest.version).toBe("0.1.0");
+      expect(manifest.description).toContain("MemoryLayer.ai");
+      expect(manifest.capabilities).toBeDefined();
+    });
+
+    it("should list core tools in capabilities", () => {
+      const server = new MCPServer(client);
+      const manifest = server.getManifest();
+      const toolNames = manifest.capabilities?.tools as string[];
+
+      expect(toolNames).toContain("memory_remember");
+      expect(toolNames).toContain("memory_recall");
+    });
+  });
+
+  describe("tool listing", () => {
+    it("should include session tools when session mode enabled", () => {
+      const server = new MCPServer(client, { sessionMode: true });
+      const manifest = server.getManifest();
+
+      // The manifest only shows TOOLS, but the handler includes SESSION_TOOLS
+      // This tests that core tools are present
+      const toolNames = manifest.capabilities?.tools as string[];
+      expect(toolNames.length).toBeGreaterThan(0);
+    });
+  });
+});
+
+describe("createServer", () => {
+  let client: MemoryLayerClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new MemoryLayerClient({ baseUrl: "http://localhost:61001" });
+  });
+
+  it("should create server instance", async () => {
+    const server = await createServer(client);
+    expect(server).toBeInstanceOf(MCPServer);
+  });
+
+  it("should pass options to server", async () => {
+    const server = await createServer(client, {
+      workspaceId: "my-workspace",
+      sessionMode: false,
+    });
+    expect(server).toBeInstanceOf(MCPServer);
+  });
+});
+
+describe("Tool counts", () => {
+  it("should have expected number of core tools", () => {
+    // memory_remember, memory_recall, memory_reflect, memory_forget,
+    // memory_associate, memory_briefing, memory_statistics, memory_graph_query, memory_audit
+    expect(TOOLS.length).toBe(9);
+  });
+
+  it("should have expected number of session tools", () => {
+    // memory_session_start, memory_session_end, memory_session_commit, memory_session_status
+    expect(SESSION_TOOLS.length).toBe(4);
+  });
+
+  it("should have expected number of context environment tools", () => {
+    // memory_context_exec, memory_context_inspect, memory_context_load,
+    // memory_context_inject, memory_context_query, memory_context_rlm,
+    // memory_context_status, memory_context_checkpoint
+    expect(CONTEXT_ENVIRONMENT_TOOLS.length).toBe(8);
+  });
+
+  it("should have 21 total tools when combined", () => {
+    expect(TOOLS.length + SESSION_TOOLS.length + CONTEXT_ENVIRONMENT_TOOLS.length).toBe(21);
+  });
+});

package/tests/session.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Tests for SessionManager
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { SessionManager } from "../src/session.js";
+
+describe("SessionManager", () => {
+  let manager: SessionManager;
+
+  beforeEach(() => {
+    manager = new SessionManager();
+  });
+
+  describe("constructor", () => {
+    it("should be enabled by default", () => {
+      expect(manager.isEnabled).toBe(true);
+    });
+
+    it("should respect enabled config", () => {
+      const disabled = new SessionManager({ enabled: false });
+      expect(disabled.isEnabled).toBe(false);
+    });
+
+    it("should have no active session initially", () => {
+      expect(manager.hasActiveSession).toBe(false);
+      expect(manager.currentSession).toBeNull();
+    });
+  });
+
+  describe("startSession", () => {
+    it("should create a new session", () => {
+      const session = manager.startSession("test-workspace");
+
+      expect(session).toBeDefined();
+      expect(session.id).toMatch(/^local_\d+_[a-z0-9]+$/);
+      expect(session.workspaceId).toBe("test-workspace");
+      expect(session.committed).toBe(false);
+      expect(session.workingMemory.size).toBe(0);
+    });
+
+    it("should set hasActiveSession to true", () => {
+      manager.startSession("test-workspace");
+      expect(manager.hasActiveSession).toBe(true);
+    });
+
+    it("should store server session ID if provided", () => {
+      const session = manager.startSession("test-workspace", "server-123");
+      expect(session.serverSessionId).toBe("server-123");
+    });
+
+    it("should replace existing session", () => {
+      const first = manager.startSession("workspace-1");
+      const second = manager.startSession("workspace-2");
+
+      expect(manager.currentSession?.id).toBe(second.id);
+      expect(manager.currentSession?.workspaceId).toBe("workspace-2");
+    });
+  });
+
+  describe("endSession", () => {
+    it("should return null if no active session", () => {
+      const result = manager.endSession();
+      expect(result).toBeNull();
+    });
+
+    it("should return the ended session", () => {
+      const started = manager.startSession("test-workspace");
+      const ended = manager.endSession();
+
+      expect(ended?.id).toBe(started.id);
+    });
+
+    it("should clear the active session", () => {
+      manager.startSession("test-workspace");
+      manager.endSession();
+
+      expect(manager.hasActiveSession).toBe(false);
+      expect(manager.currentSession).toBeNull();
+    });
+  });
+
+  describe("markCommitted", () => {
+    it("should mark session as committed", () => {
+      manager.startSession("test-workspace");
+      manager.markCommitted();
+
+      expect(manager.currentSession?.committed).toBe(true);
+    });
+
+    it("should do nothing if no active session", () => {
+      // Should not throw
+      manager.markCommitted();
+    });
+  });
+
+  describe("working memory", () => {
+    beforeEach(() => {
+      manager.startSession("test-workspace");
+    });
+
+    describe("getAllWorkingMemory", () => {
+      it("should return empty array for new session", () => {
+        const entries = manager.getAllWorkingMemory();
+        expect(entries).toEqual([]);
+      });
+
+      it("should return empty array if no session", () => {
+        manager.endSession();
+        const entries = manager.getAllWorkingMemory();
+        expect(entries).toEqual([]);
+      });
+    });
+
+    describe("clearWorkingMemory", () => {
+      it("should not throw on empty working memory", () => {
+        expect(() => manager.clearWorkingMemory()).not.toThrow();
+        expect(manager.getAllWorkingMemory()).toHaveLength(0);
+      });
+    });
+  });
+
+  describe("getSessionSummary", () => {
+    it("should return inactive status when no session", () => {
+      const summary = manager.getSessionSummary();
+      expect(summary.active).toBe(false);
+    });
+
+    it("should return session info when active", () => {
+      manager.startSession("test-workspace", "server-123");
+
+      const summary = manager.getSessionSummary();
+
+      expect(summary.active).toBe(true);
+      expect(summary.workspaceId).toBe("test-workspace");
+      expect(summary.serverSessionId).toBe("server-123");
+      expect(summary.workingMemoryCount).toBe(0);
+      expect(summary.committed).toBe(false);
+    });
+  });
+
+  describe("getTtlSeconds", () => {
+    it("should return default TTL", () => {
+      expect(manager.getTtlSeconds()).toBe(3600);
+    });
+
+    it("should return custom TTL", () => {
+      const custom = new SessionManager({ ttlSeconds: 7200 });
+      expect(custom.getTtlSeconds()).toBe(7200);
+    });
+  });
+});

package/tests/tools.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Tests for MCP tool definitions
+ */
+
+import { describe, it, expect } from "vitest";
+import { TOOLS, SESSION_TOOLS, CONTEXT_ENVIRONMENT_TOOLS, CORE_TOOLS, EXTENDED_TOOLS } from "../src/tools.js";
+
+describe("Tool Definitions", () => {
+  describe("TOOLS", () => {
+    it("should export core memory tools", () => {
+      const toolNames = TOOLS.map(t => t.name);
+
+      expect(toolNames).toContain("memory_remember");
+      expect(toolNames).toContain("memory_recall");
+      expect(toolNames).toContain("memory_reflect");
+      expect(toolNames).toContain("memory_forget");
+      expect(toolNames).toContain("memory_associate");
+      expect(toolNames).toContain("memory_briefing");
+      expect(toolNames).toContain("memory_statistics");
+      expect(toolNames).toContain("memory_graph_query");
+      expect(toolNames).toContain("memory_audit");
+    });
+
+    it("should have valid input schemas", () => {
+      for (const tool of TOOLS) {
+        expect(tool.inputSchema).toBeDefined();
+        expect(tool.inputSchema.type).toBe("object");
+        expect(tool.inputSchema.properties).toBeDefined();
+      }
+    });
+
+    it("should have descriptions for all tools", () => {
+      for (const tool of TOOLS) {
+        expect(tool.description).toBeDefined();
+        expect(tool.description.length).toBeGreaterThan(10);
+      }
+    });
+  });
+
+  describe("SESSION_TOOLS", () => {
+    it("should export session management tools", () => {
+      const toolNames = SESSION_TOOLS.map(t => t.name);
+
+      expect(toolNames).toContain("memory_session_start");
+      expect(toolNames).toContain("memory_session_end");
+      expect(toolNames).toContain("memory_session_commit");
+      expect(toolNames).toContain("memory_session_status");
+    });
+
+    it("should have valid input schemas", () => {
+      for (const tool of SESSION_TOOLS) {
+        expect(tool.inputSchema).toBeDefined();
+        expect(tool.inputSchema.type).toBe("object");
+      }
+    });
+
+    it("should have descriptions for all tools", () => {
+      for (const tool of SESSION_TOOLS) {
+        expect(tool.description).toBeDefined();
+        expect(tool.description.length).toBeGreaterThan(10);
+      }
+    });
+  });
+
+  describe("CONTEXT_ENVIRONMENT_TOOLS", () => {
+    it("should export context environment tools", () => {
+      const toolNames = CONTEXT_ENVIRONMENT_TOOLS.map(t => t.name);
+
+      expect(toolNames).toContain("memory_context_exec");
+      expect(toolNames).toContain("memory_context_inspect");
+      expect(toolNames).toContain("memory_context_load");
+      expect(toolNames).toContain("memory_context_inject");
+      expect(toolNames).toContain("memory_context_query");
+      expect(toolNames).toContain("memory_context_rlm");
+      expect(toolNames).toContain("memory_context_status");
+      expect(toolNames).toContain("memory_context_checkpoint");
+    });
+
+    it("should have valid input schemas", () => {
+      for (const tool of CONTEXT_ENVIRONMENT_TOOLS) {
+        expect(tool.inputSchema).toBeDefined();
+        expect(tool.inputSchema.type).toBe("object");
+      }
+    });
+
+    it("should have descriptions for all tools", () => {
+      for (const tool of CONTEXT_ENVIRONMENT_TOOLS) {
+        expect(tool.description).toBeDefined();
+        expect(tool.description.length).toBeGreaterThan(10);
+      }
+    });
+  });
+
+  describe("memory_remember tool", () => {
+    const tool = TOOLS.find(t => t.name === "memory_remember");
+
+    it("should require content", () => {
+      expect(tool?.inputSchema.required).toContain("content");
+    });
+
+    it("should have memory type enum", () => {
+      const typeProperty = tool?.inputSchema.properties?.type;
+      expect(typeProperty?.enum).toContain("episodic");
+      expect(typeProperty?.enum).toContain("semantic");
+      expect(typeProperty?.enum).toContain("procedural");
+      expect(typeProperty?.enum).toContain("working");
+    });
+
+    it("should have importance range", () => {
+      const importance = tool?.inputSchema.properties?.importance;
+      expect(importance?.minimum).toBe(0);
+      expect(importance?.maximum).toBe(1);
+    });
+  });
+
+  describe("memory_recall tool", () => {
+    const tool = TOOLS.find(t => t.name === "memory_recall");
+
+    it("should require query", () => {
+      expect(tool?.inputSchema.required).toContain("query");
+    });
+
+    it("should have limit constraints", () => {
+      const limit = tool?.inputSchema.properties?.limit;
+      expect(limit?.minimum).toBe(1);
+      expect(limit?.maximum).toBe(100);
+    });
+  });
+
+  describe("memory_associate tool", () => {
+    const tool = TOOLS.find(t => t.name === "memory_associate");
+
+    it("should require source_id, target_id, and relationship", () => {
+      expect(tool?.inputSchema.required).toContain("source_id");
+      expect(tool?.inputSchema.required).toContain("target_id");
+      expect(tool?.inputSchema.required).toContain("relationship");
+    });
+
+    it("should have relationship description", () => {
+      const relationship = tool?.inputSchema.properties?.relationship;
+      expect(relationship?.type).toBe("string");
+      expect(relationship?.description).toBeDefined();
+    });
+  });
+
+  describe("memory_context_exec tool", () => {
+    const tool = CONTEXT_ENVIRONMENT_TOOLS.find(t => t.name === "memory_context_exec");
+
+    it("should require code", () => {
+      expect(tool?.inputSchema.required).toContain("code");
+    });
+
+    it("should have return_result option", () => {
+      const returnResult = tool?.inputSchema.properties?.return_result;
+      expect(returnResult?.type).toBe("boolean");
+    });
+  });
+
+  describe("memory_session_end tool", () => {
+    const tool = SESSION_TOOLS.find(t => t.name === "memory_session_end");
+
+    it("should have commit option", () => {
+      expect(tool?.inputSchema.properties?.commit).toBeDefined();
+      expect(tool?.inputSchema.properties?.commit?.type).toBe("boolean");
+    });
+
+    it("should have importance_threshold option", () => {
+      const threshold = tool?.inputSchema.properties?.importance_threshold;
+      expect(threshold?.minimum).toBe(0);
+      expect(threshold?.maximum).toBe(1);
+    });
+  });
+
+  describe("Legacy exports", () => {
+    it("should export CORE_TOOLS as filtered subset of TOOLS", () => {
+      const coreNames = CORE_TOOLS.map(t => t.name);
+      expect(coreNames).toEqual([
+        "memory_remember", "memory_recall", "memory_reflect",
+        "memory_forget", "memory_associate"
+      ]);
+    });
+
+    it("should export EXTENDED_TOOLS as filtered subset of TOOLS", () => {
+      const extNames = EXTENDED_TOOLS.map(t => t.name);
+      expect(extNames).toEqual([
+        "memory_briefing", "memory_statistics",
+        "memory_graph_query", "memory_audit"
+      ]);
+    });
+  });
+});

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["tests/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      include: ["src/**/*.ts"],
+      exclude: ["src/index.ts", "src/types.ts"],
+    },
+  },
+});