MCP Server

The MemoryLayer MCP server (@scitrera/memorylayer-mcp-server) provides memory tools for LLM agents to store, recall, synthesize, and manage information across sessions via the Model Context Protocol.

Installation

npm install @scitrera/memorylayer-mcp-server

Quick Start

# Set environment variables
export MEMORYLAYER_URL=http://localhost:61001
export MEMORYLAYER_WORKSPACE_ID=my-workspace

# Run the server
npx memorylayer-mcp

Configuration for Claude Code

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.

Or via CLI:

claude mcp add --transport stdio memorylayer \
  --env MEMORYLAYER_URL=http://localhost:61001 \
  -- npx @scitrera/memorylayer-mcp-server

Configuration for Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "memorylayer": {
      "command": "npx",
      "args": ["@scitrera/memorylayer-mcp-server"],
      "env": {
        "MEMORYLAYER_URL": "http://localhost:61001",
        "MEMORYLAYER_WORKSPACE_ID": "my-project"
      }
    }
  }
}

Environment Variables

Variable	Description	Default
MEMORYLAYER_URL	Base URL for MemoryLayer API	http://localhost:61001
MEMORYLAYER_API_KEY	API key for authentication	—
MEMORYLAYER_WORKSPACE_ID	Workspace ID (overrides auto-detection)	auto-detected
MEMORYLAYER_AUTO_WORKSPACE	Set to false to disable auto-detection	true
MEMORYLAYER_SESSION_MODE	Set to false to disable session/working memory	true
MEMORYLAYER_TOOL_PROFILE	Tool profile: cc (default), full, or minimal	cc
MEMORYLAYER_AUTO_START_SESSION	Set to false to disable auto-starting session	true

Tool Profiles

The MCP server supports three tool profiles that control which tools are exposed to the LLM. Set via the MEMORYLAYER_TOOL_PROFILE environment variable.

cc — Claude Code (Default)

The recommended profile for Claude Code. Provides 25 tools optimized for the agent memory workflow:

• Core memory: memory_remember, memory_recall, memory_reflect, memory_forget
• Utility: memory_briefing
• Session management: memory_session_start, memory_session_end, memory_session_commit, memory_session_status
• Context environment: all 8 context tools
• Chat history: chat_thread_create, chat_thread_append, chat_thread_get, chat_thread_list
• Skills (read): skills_list, skills_get, skills_get_file, skills_search

Excludes advanced tools (memory_associate, memory_statistics, memory_graph_query, memory_audit), destructive chat tools (chat_thread_decompose, chat_thread_delete), skills_save, and the mcp_servers_* registry tools to keep the surface focused.

full — All Tools

All 38 tools enabled. For power users, debugging, or advanced graph-based memory use cases. Adds on top of cc:

• memory_associate — graph building
• memory_statistics — workspace analytics (placeholder; not yet implemented server-side)
• memory_graph_query — multi-hop graph traversal
• memory_audit — contradiction detection (placeholder; not yet implemented server-side)
• chat_thread_decompose — memory extraction from threads
• chat_thread_delete — thread deletion
• skills_save — create/update skill assets
• mcp_servers_list, mcp_servers_get, mcp_servers_save, mcp_servers_delete, mcp_servers_import — MCP server registry

minimal — Essentials Only

Just 2 tools: memory_remember and memory_recall. For testing or extremely constrained environments.

Complete Tool Reference

Core Memory Tools

memory_remember

Store a new memory for later recall. Use for facts, preferences, decisions, or events worth remembering.

Parameter	Type	Required	Default	Description
content	string	Yes	—	The memory content to store
type	string	No	—	Memory type: episodic (events), semantic (facts), procedural (how-to), working (current context)
importance	number	No	0.5	How important (0-1). Higher values = retained longer and ranked higher in recall
tags	string[]	No	—	Tags for categorization (e.g., ["python", "bug-fix"])
subtype	string	No	—	Domain classification: solution, problem, code_pattern, fix, error, workflow, preference, decision, directive

{
  "content": "User prefers TypeScript for new projects",
  "type": "semantic",
  "importance": 0.8,
  "tags": ["preference", "typescript"],
  "subtype": "preference"
}

memory_recall

Search memories by semantic query. Returns relevant memories ranked by relevance.

Parameter	Type	Required	Default	Description
query	string	Yes	—	Natural language query (e.g., “How do I fix authentication errors?”)
types	string[]	No	—	Filter by memory types: episodic, semantic, procedural, working
limit	integer	No	10	Max memories to return (1-100)
min_relevance	number	No	server default	Min relevance score (0-1)
tags	string[]	No	—	Filter by tags (AND logic)

{
  "query": "What are the user's coding preferences?",
  "limit": 10,
  "min_relevance": 0.5,
  "types": ["semantic"],
  "tags": ["preference"]
}

memory_reflect

Synthesize and summarize memories matching a query. Use when you need insights across multiple memories rather than individual recall results.

Parameter	Type	Required	Default	Description
query	string	Yes	—	What to reflect on
detail_level	string	No	server default	Level of detail: abstract (brief), overview (medium), full (detailed)
include_sources	boolean	No	true	Include source memory IDs in response
depth	integer	No	2	Association traversal depth, how many hops to follow (1-5)

{
  "query": "What patterns have we seen with database performance?",
  "detail_level": "overview",
  "include_sources": true,
  "depth": 2
}

memory_forget

Delete or decay a memory when information is outdated or incorrect. Use sparingly — memories are useful historical context.

Parameter	Type	Required	Default	Description
memory_id	string	Yes	—	ID of memory to forget
reason	string	No	—	Why this memory should be forgotten (for audit trail)
hard	boolean	No	false	Hard delete (permanent) vs soft delete (recoverable)

memory_associate

Link two memories with a relationship. Helps build knowledge graph for traversal and causal reasoning.

Profile: full only

Parameter	Type	Required	Default	Description
source_id	string	Yes	—	Source memory ID
target_id	string	Yes	—	Target memory ID
relationship	string	Yes	—	Relationship type (e.g., causes, solves, similar_to, part_of, related_to). The server supports 63 relationship types from its ontology.
strength	number	No	0.8	Strength of association (0-1)

{
  "source_id": "mem_problem",
  "target_id": "mem_solution",
  "relationship": "solves",
  "strength": 0.9
}

memory_briefing

Get a session briefing summarizing recent activity and context. Returns workspace stats and recent memory content at configurable detail level. Use at session start or after compaction to regain context.

Parameter	Type	Required	Default	Description
time_window_minutes	number	No	60	Time window in minutes for recent memories
detail_level	string	No	abstract	Level of detail: abstract (summaries), overview (more detail), full (complete content)
limit	number	No	10	Maximum number of recent memories to include (max: 50)
include_memories	boolean	No	true	Whether to include recent memory content
include_contradictions	boolean	No	true	Flag contradicting memories in briefing

memory_statistics

Get memory statistics and analytics for the workspace.

Profile: full only

Parameter	Type	Required	Default	Description
include_breakdown	boolean	No	true	Include breakdown by type/subtype

memory_graph_query

Multi-hop graph traversal to find related memories. Use to discover causal chains or knowledge paths.

Profile: full only

Parameter	Type	Required	Default	Description
start_memory_id	string	Yes	—	Starting memory ID
relationship_types	string[]	No	—	Filter by relationship types (e.g., ["causes", "triggers"])
max_depth	integer	No	3	Maximum traversal depth (1-5)
direction	string	No	both	Traversal direction: outgoing, incoming, both
max_paths	integer	No	50	Maximum paths to return

{
  "start_memory_id": "mem_abc123",
  "relationship_types": ["causes", "triggers"],
  "max_depth": 3,
  "direction": "both"
}

memory_audit

Audit memories for contradictions and inconsistencies. Use to maintain knowledge base health.

Profile: full only

Parameter	Type	Required	Default	Description
memory_id	string	No	—	Specific memory to audit (omit to audit entire workspace)
auto_resolve	boolean	No	false	Automatically mark newer contradicting memories as preferred

Session Management Tools

memory_session_start

Start a new session for working memory. Called automatically by the SessionStart hook, but can be called manually. After context compaction, call memory_context_inspect to re-orient with existing sandbox state.

Parameter	Type	Required	Default	Description
metadata	object	No	—	Optional metadata to attach to the session

memory_session_end

End the current session and optionally commit working memory to long-term storage. Called automatically by the Stop hook.

Parameter	Type	Required	Default	Description
commit	boolean	No	true	Whether to commit working memory to long-term storage
importance_threshold	number	No	0.5	Minimum importance for extracted memories (0-1)

memory_session_commit

Commit working memory to long-term storage WITHOUT ending the session. Use for checkpoints during long sessions or before potential interruptions. The session remains active after commit.

Parameter	Type	Required	Default	Description
importance_threshold	number	No	0.5	Minimum importance for extracted memories (0-1)
clear_after_commit	boolean	No	false	Clear working memory after commit (session stays active)

memory_session_status

Get current session status including working memory summary. Use to check if a session is active. No parameters.

Context Environment Tools

These tools provide a persistent Python execution environment on the server. Sandbox state survives context compaction — call memory_context_inspect after compaction to re-orient.

memory_context_exec

Execute Python code in the server-side sandbox. Variables from prior exec calls are available. Use for data transformation, analysis, and computation on loaded memories.

Parameter	Type	Required	Default	Description
code	string	Yes	—	Python code to execute. Variables from prior exec calls are available.
result_var	string	No	—	Store the expression result in this variable name
return_result	boolean	No	true	Return execution output to caller. Set false for large intermediate results.
max_return_chars	integer	No	10000	Maximum characters to return. Output beyond this is truncated.

memory_context_inspect

Inspect variables in the server-side sandbox. Omit variable name for an overview of all variables, or specify one for detailed inspection. Call this after context compaction or at the start of continued sessions to re-orient.

Parameter	Type	Required	Default	Description
variable	string	No	—	Inspect a specific variable. Omit for overview of all variables.
preview_chars	integer	No	200	Characters to include in value previews

memory_context_load

Load memories from the store into a sandbox variable via semantic search. The loaded memories become available for exec, query, and RLM operations.

Parameter	Type	Required	Default	Description
var	string	Yes	—	Variable name to store loaded memories
query	string	Yes	—	Semantic search query
limit	integer	No	50	Maximum memories to load
types	string[]	No	—	Filter by memory types
tags	string[]	No	—	Filter by tags
min_relevance	number	No	—	Minimum relevance score (0-1)
include_embeddings	boolean	No	false	Include embedding vectors (large)

memory_context_inject

Inject a value directly into the server-side sandbox as a named variable. Use to pass data from the client into the execution environment.

Parameter	Type	Required	Default	Description
key	string	Yes	—	Variable name in sandbox
value	string	Yes	—	Value to store (string, JSON string, or code snippet)
parse_json	boolean	No	false	Parse value as JSON before storing (creates dict/list, not string)

memory_context_query

Ask the server-side LLM a question using sandbox variables as context. The LLM sees the variable data and answers your prompt.

Parameter	Type	Required	Default	Description
prompt	string	Yes	—	Question or instruction for the server LLM
variables	string[]	Yes	—	Variable names to include as context
max_context_chars	integer	No	server default	Max chars of variable data to send to LLM
result_var	string	No	—	Store LLM response in this variable

memory_context_rlm

Run a Recursive Language Model (RLM) loop: the server LLM iteratively reasons over sandbox data and memories to achieve a goal. Returns a synthesis of findings.

Parameter	Type	Required	Default	Description
goal	string	Yes	—	Natural language goal for the RLM loop
memory_query	string	No	—	Semantic query to pre-load memories before the loop starts
memory_limit	integer	No	100	Max memories to pre-load
max_iterations	integer	No	10	Maximum RLM loop iterations (1-50)
variables	string[]	No	—	Existing sandbox variables to include as context
result_var	string	No	—	Store the final synthesis in this variable
detail_level	string	No	standard	Detail level: brief, standard, detailed

memory_context_status

Get the status of the server-side context environment including sandbox state, active variables, and resource usage. Use after context compaction to check if a sandbox environment still exists. No parameters.

memory_context_checkpoint

Checkpoint the sandbox state for persistence. Fires persistence hooks so enterprise deployments can save sandbox state to durable storage. No parameters.

Chat History Tools

chat_thread_create

Create a new chat thread for storing conversation history. Threads persist messages over time and can auto-decompose into memories.

Parameter	Type	Required	Default	Description
thread_id	string	No	auto-generated	Client-provided thread ID
user_id	string	No	—	User who owns this conversation
observer_id	string	No	—	Observer entity ID (typically the AI agent)
subject_id	string	No	—	Subject entity ID (typically the human user)
title	string	No	—	Optional display title
metadata	object	No	—	Arbitrary metadata

chat_thread_append

Append messages to a chat thread. Messages are stored persistently and will be decomposed into memories when a threshold is reached.

Parameter	Type	Required	Default	Description
thread_id	string	Yes	—	Thread to append to
messages	object[]	Yes	—	Messages to append. Each message has role (required: user/assistant/system/tool), content (required), and optional metadata.

chat_thread_get

Get a chat thread with its messages. Returns thread metadata and paginated messages.

Parameter	Type	Required	Default	Description
thread_id	string	Yes	—	Thread ID to retrieve
limit	integer	No	100	Max messages to return
offset	integer	No	0	Message pagination offset
order	string	No	asc	Message order: asc or desc

chat_thread_list

List chat threads in the workspace, optionally filtered by user.

Parameter	Type	Required	Default	Description
user_id	string	No	—	Filter by user ID
limit	integer	No	50	Max threads to return
offset	integer	No	0	Pagination offset

chat_thread_decompose

Trigger memory decomposition for a thread’s unprocessed messages. Extracts memories from chat history.

Profile: full only

Parameter	Type	Required	Default	Description
thread_id	string	Yes	—	Thread to decompose

chat_thread_delete

Delete a chat thread and all its messages.

Profile: full only

Parameter	Type	Required	Default	Description
thread_id	string	Yes	—	Thread to delete

Workspace Detection

The server determines your workspace in this order:

1. MEMORYLAYER_WORKSPACE_ID environment variable (explicit override)
2. Git remote origin — extracts repo name from remote URL
3. Git root directory — uses the root folder name
4. Current directory — falls back to the current working directory name

Programmatic Usage

import { MemoryLayerClient, createServer } from "@scitrera/memorylayer-mcp-server";

const client = new MemoryLayerClient({
  baseUrl: "http://localhost:61001",
  workspaceId: "my-workspace",
});

const server = await createServer(client);
await server.run();