MCP Tools

Call Neuroloom's memory and session operations as MCP tools from Claude Code, Cursor, Windsurf, or any MCP-compatible agent. This page documents all 28 tools with their parameters, required values, and usage patterns.

For setup instructions, see the Quickstart. For session lifecycle concepts, see Session Lifecycle. For a worked integration, see Coding Agent Memory cookbook.

Connection

Connect to the hosted MCP server using the Streamable HTTP transport:

{
  "mcpServers": {
    "neuroloom": {
      "type": "http",
      "url": "https://mcp.neuroloom.dev/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

Or from the CLI:

# Project-scoped (shared via .mcp.json)
claude mcp add-json neuroloom -s project '{"type":"http","url":"https://mcp.neuroloom.dev/mcp","headers":{"Authorization":"Bearer nl_your_api_key_here"}}'

# User-scoped (personal, not committed)
claude mcp add-json neuroloom -s user '{"type":"http","url":"https://mcp.neuroloom.dev/mcp","headers":{"Authorization":"Bearer nl_your_api_key_here"}}'

Transport Restrictions

Some tools are only available on specific transports:

stdio-only tools (not available on the hosted HTTP server):

• document_ingest_file
• document_ingest_files_batch
• document_ingest_batch_from_file
• sdlc_seed_from_file

HTTP-only tools (not available on stdio):

• document_ingest_batch_get_upload_url
• sdlc_seed_get_upload_url

Memory Tools (10)

memory_search

Search cross-session memory with semantic and keyword matching. Combines pgvector cosine similarity with keyword frequency scoring. The most common tool — call before starting any non-trivial task to surface relevant past decisions and patterns.

Parameters

Example

memory_search(
  query="error handling patterns for async FastAPI endpoints",
  memory_types=["pattern", "convention", "incident"],
  min_importance=0.6,
  limit=10
)

memory_get_detail

Retrieve the full record for a single memory, including its relationship graph. Returns the complete entry: narrative, tags, concepts, source files, importance and confidence scores, and relationship edges. Use after memory_search to read the complete context for a specific memory.

Also records an access event on the memory, incrementing access_count.

Parameters

Example

memory_get_detail(
  memory_id="mem-a1b2c3d4e5f6g7h8",
  include_related=true
)

memory_get_timeline

List recent memories ordered by creation time descending. Useful for understanding what was captured during a recent work period or reviewing what was stored in the last session.

Parameters

Example

memory_get_timeline(days=3, limit=20)

memory_get_index

Return a lightweight title-and-type index of all memories. The most token-efficient way to survey your workspace. Use this for a quick overview, then memory_get_detail to read specific entries in full.

Parameters

Example

memory_get_index(limit=100)

memory_get_related

Find memories semantically similar to a given memory using pgvector cosine similarity on stored embeddings. Requires the source memory to have a generated embedding — if not yet computed, returns an empty list.

Parameters

Example

memory_get_related(
  memory_id="mem-a1b2c3d4e5f6g7h8",
  limit=5
)

memory_by_file

Find memories that reference a specific file path. Use when opening a file to surface past decisions and patterns captured while working on it. Partial path matches are supported — database.py matches api/neuroloom_api/database.py.

This tool is a convenience wrapper that calls the search endpoint with a files filter.

Parameters

Example

memory_by_file(
  file_path="api/neuroloom_api/routers/memories.py",
  limit=15
)

memory_store

Persist a pre-structured memory directly to the workspace. Bypasses the observation pipeline — use when you have already synthesised a well-formed insight and want to store it immediately. After storing, the API enqueues embedding generation and relationship discovery in the background.

Parameters

Example

memory_store(
  title="Use HNSW index with m=16, ef_construction=64 for pgvector",
  memory_type="decision",
  content="HNSW index parameters: m=16 and ef_construction=64 give good recall at acceptable build time. Use ef_search=40 as the query default, bumping to 100-200 for high-recall scenarios. Index is non-transactional — rollbacks do not undo index updates.",
  tags=["pgvector", "hnsw", "performance"],
  concepts=["vector-search", "database-indexing"],
  files=["api/neuroloom_api/models.py"],
  importance=0.88,
  confidence=0.95
)

memory_rate

Rate a memory's usefulness after retrieval or use. Call after using (or deciding not to use) a retrieved memory. Positive ratings increase the memory's importance score over time; negative ratings decrease it during the next scheduled recalculation.

Parameters

Example

memory_rate(
  memory_id="mem-a1b2c3d4e5f6g7h8",
  useful=true,
  context="The selectinload pattern resolved the N+1 query issue immediately."
)

memory_explore

Seed a topic exploration using a query, then expand through relationship edges to return a bounded subgraph of connected memories. Use this to understand how a topic spreads across your workspace relationship graph, or to build richer context injections.

Parameters

Example

memory_explore(
  query="error handling and resilience patterns",
  max_nodes=25,
  relationship_types=["similar_to", "references"],
  min_edge_confidence=0.65,
  seed_limit=3
)

workspace_insight

Return a concise snapshot of what the memory engine knows about this project. Use this to answer "What does Neuroloom know about this project?", "How many memories have been stored?", or "When was the last memory added?" Also called internally by the /neuroloom:status slash command.

Parameters

Example

workspace_insight()

Response fields

Session Tools (3)

session_start

Start a new Neuroloom session and retrieve initial memory context. Call at the beginning of a work session to register it with Neuroloom and receive relevant past memories for context injection.

The returned session_id must be passed to session_end and session_get_context.

Parameters

Example

session_start(
  project_path="/Users/dev/projects/neuroloom"
)

Response includes session_id (a sess- prefixed string), started_at, and the initial memory context block ready for injection.

session_end

End an active Neuroloom session. Marks the session inactive and enqueues an async batch extraction job that processes observations into structured memories. The response is returned immediately — extraction runs in the background.

Parameters

Example

session_end(
  session_id="sess-abc123",
  summary="Implemented D38 graph API. Explore and path endpoints now live with BFS traversal. Added pagerank_score and community_label fields to memory responses."
)

session_get_context

Retrieve relevant memory context for an active session. Returns recent high-importance memories from the workspace for context injection. Use after session_start or mid-session to refresh context when switching to a new area of work.

Parameters

Example

session_get_context(
  session_id="sess-abc123",
  max_memories=15
)

Document Tools (6)

Document tools ingest structured content (markdown, plaintext, PDFs) into the workspace as memories. Useful for bulk-loading existing documentation, wikis, or decision logs.

document_ingest

Ingest a single document by passing its content directly. Creates one or more memories from the document's content using the workspace's extraction pipeline.

Parameters

document_ingest_batch

Ingest multiple documents in a single call by passing a list of document objects. Each document is processed independently.

Parameters

document_ingest_file

Ingest a file from the local filesystem by path. Reads the file and ingests its contents.

Parameters

document_ingest_files_batch

Ingest multiple files from the local filesystem in a single call.

Parameters

document_ingest_batch_from_file

Ingest a batch of documents defined in a JSON file on the local filesystem.

Parameters

document_ingest_batch_get_upload_url

Get a pre-signed upload URL for uploading a batch document file to the hosted MCP server. Use when running in HTTP transport mode and you need to upload large document batches.

Parameters

SDLC Tools (4)

SDLC tools ingest structured knowledge from SDLC deliverables (specs, plans, results) as memories. Designed for the Neuroloom SDLC plugin.

sdlc_seed

Seed the workspace with SDLC knowledge by passing structured content directly. Creates memories from SDLC deliverable content (specs, plans, results, changelogs).

Parameters

sdlc_seed_from_file

Seed the workspace from a local SDLC document file.

Parameters

sdlc_seed_get_upload_url

Get a pre-signed upload URL for uploading SDLC document files to the hosted MCP server.

Parameters

sdlc_get_version

Return the current SDLC plugin version and server version. Use to confirm compatibility between your local plugin and the hosted MCP server.

Parameters

None.

Example

sdlc_get_version()

Code Graph Tools (5)

Code graph tools query the CodeWeaver structural index — functions, classes, and modules parsed from your codebase. These tools require the CodeWeaver code graph to be populated (run the neuroloom:init skill or seed_code_graph.py locally first).

code_search

Find functions, classes, or modules by name or file pattern. Use this to resolve a function name to its symbol_id before calling code_callers, code_callees, or code_context.

Parameters

Example

code_search(q="createUser", symbol_type="function")

code_navigate

See what calls a function and what it calls — a 1-hop graph view. Use for graph topology only. For linked memories alongside the call chain, use code_context instead.

Parameters

code_callers

Get all functions and methods that call this symbol (incoming edges only).

Parameters

code_callees

Get all functions and methods that this symbol calls (outgoing edges only).

Parameters

code_context

Given a symbol, traverse its call chain and return all linked memories. Use when you need code structure and memory context together — answers "what do we know about this function and everything it touches?". Provide either symbol_id (from code_search) or symbol_name with an optional file_path for name-based lookup.

Parameters

Example

code_context(symbol_name="get_memories", file_path="api/routers/memories.py")

Tool Summary

Troubleshooting

Related

• Quickstart — install and configure the plugin or direct MCP access
• Memory Lifecycle — how MCP tool calls feed the observation and extraction pipeline
• Coding Agent Memory — worked example using MCP tools in a coding workflow