@scitrera/memorylayer-mcp-server

TypeScript MCP (Model Context Protocol) server for MemoryLayer.ai.

Provides 25 memory tools by default (38 in the full profile) for LLM agents to store, recall, synthesize, and manage information across sessions.

Installation

npm install @scitrera/memorylayer-mcp-server

Quick Start

As a Standalone MCP Server

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

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:

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

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

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):

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

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();

Tool Profiles

Tools are organized into profiles selected via MEMORYLAYER_TOOL_PROFILE:

| Profile | Count | Description | |---------|-------|-------------| | cc (default) | 25 | Optimized for Claude Code: core memory + sessions + context environment + chat threads + skills (read) | | full | 38 | All tools: adds associate, statistics, graph_query, audit, chat_thread_decompose, chat_thread_delete, skills_save, and the 5 mcp_servers_* tools | | minimal | 2 | Just memory_remember and memory_recall |

memory_statistics and memory_audit ship as placeholders in the current build; their handlers return not_implemented server-side.

Available Tools

Core Memory Tools (5)

1. memory_remember

Store a new memory for later recall.

{
  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.

{
  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.

{
  query: "What patterns have we seen with database performance?",
  detail_level: "overview",  // "abstract", "overview", or "full"
  include_sources: true,
  depth: 2                   // Association traversal depth
}

4. memory_forget

Delete or decay outdated information.

{
  memory_id: "mem_abc123",
  reason: "Outdated information",
  hard: false             // true = permanent delete
}

5. memory_associate

Link memories with typed relationships.

{
  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.

{
  lookback_hours: 24,
  include_contradictions: true
}

7. memory_statistics

Get workspace analytics and memory usage.

{
  include_breakdown: true  // Include breakdown by type/subtype
}

8. memory_graph_query

Multi-hop graph traversal for causal chains.

{
  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.

{
  memory_id: "mem_abc123",  // Optional - omit to audit entire workspace
  auto_resolve: false       // Auto-prefer newer contradicting memories
}

Session Management Tools (4)

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.

{
  metadata: { task: "debugging" }  // Optional metadata
}

11. memory_session_end

End the current session and optionally commit working memory.

{
  commit: true,               // Commit to long-term storage
  importance_threshold: 0.5   // Min importance for extracted memories
}

12. memory_session_commit

Checkpoint working memory mid-session without ending it.

{
  importance_threshold: 0.5,  // Min importance for extracted memories
  clear_after_commit: false   // Clear working memory after commit
}

13. memory_session_status

Get current session status including working memory summary.

{}  // No parameters required

Context Environment Tools (8)

Server-side Python sandbox for code execution, memory analysis, and LLM-powered queries over loaded data.

14. memory_context_exec

Execute Python code in the server-side sandbox. Variables persist between calls.

{
  code: "import pandas as pd\ndf = pd.DataFrame(memories)",
  result_var: "df",           // Optional: store result in variable
  return_result: true,        // Return output to caller
  max_return_chars: 10000     // Truncate large outputs
}

15. memory_context_inspect

Inspect sandbox variables (overview or detailed view of specific variable).

{
  variable: "df",             // Optional: specific variable to inspect
  preview_chars: 200          // Characters in value previews
}

16. memory_context_load

Load memories into sandbox via semantic search.

{
  var: "relevant_memories",
  query: "authentication bugs",
  limit: 50,
  types: ["semantic", "episodic"],
  tags: ["bug-fix"],
  min_relevance: 0.6,
  include_embeddings: false
}

17. memory_context_inject

Inject data directly into sandbox as a variable.

{
  key: "config",
  value: '{"api_url": "https://api.example.com"}',
  parse_json: true            // Parse as JSON before storing
}

18. memory_context_query

Ask server-side LLM a question using sandbox variables as context.

{
  prompt: "Summarize the key patterns in these memories",
  variables: ["relevant_memories", "df"],
  max_context_chars: 50000,   // Optional limit
  result_var: "summary"       // Optional: store response
}

19. memory_context_rlm

Run Recursive Language Model loop for iterative reasoning.

{
  goal: "Identify root causes of authentication failures",
  memory_query: "authentication errors",  // Optional: pre-load memories
  memory_limit: 100,
  max_iterations: 10,
  variables: ["error_logs"],
  result_var: "analysis",
  detail_level: "detailed"    // "brief", "standard", or "detailed"
}

20. memory_context_status

Get sandbox environment status and resource usage.

{}  // No parameters required

21. memory_context_checkpoint

Checkpoint sandbox state for persistence (enterprise deployments).

{}  // 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 | | MEMORYLAYER_TOOL_PROFILE | Tool profile: cc, full, or minimal | cc | | MEMORYLAYER_AUTO_START_SESSION | Auto-start session on MCP connection | true | | MEMORYLAYER_SESSION_MODE | Enable session mode | 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 (25 in cc / 38 in full)
│   ├── client.ts      # Wrapper around @scitrera/memorylayer-sdk
│   ├── session.ts     # Local session state management
│   ├── workspace.ts   # Workspace ID auto-detection
│   ├── 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

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

npm install @scitrera/memorylayer-sdk

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 for details.

Links

• MemoryLayer.ai
• Documentation
• TypeScript SDK
• Model Context Protocol