Name	Name	Last commit message	Last commit date
parent directory ..
bin	bin
examples	examples
src	src
tests	tests
.gitignore	.gitignore
.npmignore	.npmignore
README.md	README.md
package-lock.json	package-lock.json
package.json	package.json
tsconfig.json	tsconfig.json
vitest.config.ts	vitest.config.ts

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

Uh oh!

FilesExpand file tree

memorylayer-mcp-typescript

Directory actions

More options

Directory actions

More options

Latest commit

History

memorylayer-mcp-typescript

Folders and files

parent directory

README.md

@scitrera/memorylayer-mcp-server

Installation

Quick Start

As a Standalone MCP Server

Claude Code Configuration (Recommended)

Claude Desktop Configuration

Programmatic Usage

Tool Profiles

Available Tools

Core Memory Tools (5)

1. memory_remember

2. memory_recall

3. memory_reflect

4. memory_forget

5. memory_associate

Extended Memory Tools (4)

6. memory_briefing

7. memory_statistics

8. memory_graph_query

9. memory_audit

Session Management Tools (4)

10. memory_session_start

11. memory_session_end

12. memory_session_commit

13. memory_session_status