Skip to main content
Glama
Akpughe

ultramem-mcp

by Akpughe
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

ultramem-mcp

Give any MCP client durable, cross-session memory. An MCP server that exposes an UltraMem deployment's memory layer to Claude Desktop/Code, Cursor, and any other MCP client — so your agent remembers across sessions.

It's a thin client of the UltraMem HTTP API: every tool is a call to your running ultramem-server, so there's one source of truth and nothing to keep in sync.

Tools

Tool

What it does

API

recall_search

Semantic search → relevant documents + distilled facts

POST /v1/search

recall_timeline

Newest-first enumeration over a recent window (optionally by source)

GET /v1/timeline

add_memory

Write a memory back (task outcomes, user statements)

POST /v1/memories

get_profile

The standing static + dynamic profile to inject as context

GET /v1/profile

Related MCP server: memorybank

Prerequisites

A running UltraMem server (see the UltraMem repo — cargo run -p ultramem-server or docker compose up). You need its URL and API key.

Install (one line)

No clone, no build — npx runs it straight from GitHub:

claude mcp add ultramem \
  -e ULTRAMEM_API_URL=http://localhost:8080 \
  -e ULTRAMEM_API_KEY=your-key \
  -e ULTRAMEM_CONTAINER_TAG=user_123 \
  -- npx -y github:Akpughe/ultramem-mcp
{
  "mcpServers": {
    "ultramem": {
      "command": "npx",
      "args": ["-y", "github:Akpughe/ultramem-mcp"],
      "env": {
        "ULTRAMEM_API_URL": "http://localhost:8080",
        "ULTRAMEM_API_KEY": "your-key",
        "ULTRAMEM_CONTAINER_TAG": "user_123"
      }
    }
  }
}

Configuration

Env var

Required

Default

Purpose

ULTRAMEM_API_URL

no

http://localhost:8080

Base URL of your ultramem-server.

ULTRAMEM_API_KEY

yes (if the server enforces auth)

—

Sent as Authorization: Bearer <key>.

ULTRAMEM_CONTAINER_TAG

no

server default

Namespace (one per user/agent). A tool's container_tag argument overrides it.

Security: the API key scopes a namespace — treat it like a password and never commit it.

The agent pattern

On session start, call get_profile and prepend it to the system prompt ("what you always know about the user"). During the task, recall_search for specifics and add_memory to persist outcomes. That's the "always-known context" trick, self-hosted.

Develop locally

git clone https://github.com/Akpughe/ultramem-mcp && cd ultramem-mcp
npm install          # also builds via the prepare script
node dist/index.js   # speaks JSON-RPC over stdio

Smoke-test by hand:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | ULTRAMEM_API_URL=http://localhost:8080 node dist/index.js

License

Apache-2.0.

Available Tools

4 tools
add_memoryAdd memoryA

Write a memory back to the user's store — a task outcome, a decision, or something the user just told you. It flows through the same distillation + reconciliation lifecycle as any ingested document.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleNoOptional short title.
contentYesThe text to remember.
container_tagNoNamespace to write to — omit to use the configured default.

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions the distillation and reconciliation lifecycle, which adds some behavioral insight, but does not disclose side effects, required permissions, or idempotency behavior. More explicit transparency would improve confidence for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no waste. The first sentence concisely states purpose and examples; the second adds valuable lifecycle context. Every phrase serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only 3 parameters, no output schema, and no annotations, the description provides sufficient context for typical use. It covers purpose, examples, and processing lifecycle. However, missing return value information and error behavior slightly reduce completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for each parameter. The description adds value by contextualizing the 'content' parameter (e.g., task outcome, decision), which goes beyond the schema's basic text description. This helps the agent choose appropriate content to store.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool writes a memory back to the user's store with specific examples (task outcome, decision, user statement). It is distinct from sibling tools (recall_search, recall_timeline, get_profile) which are all read-oriented.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is the tool for writing memories, but does not explicitly state when not to use it or mention alternatives. The lifecycle hint ('distillation + reconciliation') provides context but lacks explicit usage boundaries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_profileGet profileA

Fetch the standing profile for the namespace — durable facts (static) plus what the user has been doing recently (dynamic). Inject this into your system prompt to start a session already knowing the user.

ParametersJSON Schema
NameRequiredDescriptionDefault
container_tagNoNamespace — omit to use the configured default.

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the tool fetches both static and dynamic data, implying a read-only operation. It does not specify permissions or side effects, but the behavior is adequately described for a profile fetch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences: one defining the tool's action and content, and one providing immediate usage context. No superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description gives a high-level idea of the profile content but lacks specifics on return structure or fields. Given no output schema, more detail could help, but the description is still usable for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already defines the optional container_tag parameter with a clear description. The main description adds no additional parameter info, but schema coverage is 100%, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches a 'standing profile' combining static facts and dynamic recent activity. It distinguishes its purpose from siblings by focusing on profile retrieval, but does not explicitly contrast with sibling tools like recall_search or recall_timeline.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage guidance: 'Inject this into your system prompt to start a session already knowing the user.' It also explains the optional parameter behavior. However, it does not mention when not to use the tool or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recall_timelineRecall timelineA

List the user's memory items within a recent time window, newest-first — a COMPLETE enumeration (not a relevance ranking). Use it for 'what did I do/save in the last N days' questions. Optionally restrict to one source.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNoHow many days back from now to include (default 7).
limitNoMaximum items to list (default 60).
sourceNoRestrict to one source.
container_tagNoNamespace — omit to use the configured default.

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, so description carries full burden. Discloses complete enumeration (not ranking) and newest-first order, but does not mention return format, default parameter behavior, or read-only nature. Adequate but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences plus a short note on optional restriction. Front-loaded with key action and purpose. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, so description should describe what the tool returns. It says 'list memory items' but does not specify fields or structure. Could be improved by mentioning typical output fields (e.g., timestamp, content, source). Otherwise acceptable for a simple listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (baseline 3). Description adds default values for days and limit, and clarifies that container_tag is optional with a configured default, adding value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States exactly what the tool does: list memory items within a recent time window, newest-first, complete enumeration. Distinguishes from sibling recall_search (relevance ranking) and gives example use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says use for 'what did I do/save in the last N days' questions. Mentions optional source restriction. Implicitly says not to use if you need relevance ranking (use recall_search), but could explicitly mention other siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedadd_memory
    • First observedget_profile
    • First observedrecall_search
    • First observedrecall_timeline
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation5/5

All four tools have clearly distinct purposes: recall_search for semantic search, recall_timeline for chronological listing, add_memory for writing, and get_profile for fetching user profile. No overlap in functionality.

Naming Consistency5/5

Tool names follow a consistent verb_noun pattern in snake_case: recall_search, recall_timeline, add_memory, get_profile. The verbs 'recall', 'add', and 'get' are used uniformly.

Tool Count5/5

With 4 tools, the server is well-scoped for a personal memory assistant. Each tool serves a distinct operation (search, timeline, add, profile) without unnecessary bloat or deficiency.

Completeness4/5

The core operations for memory management are covered: retrieval (search and timeline), addition, and profile access. However, deletion or updating of memories is absent, which is a minor gap.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers