### Install Mnemoverse SDK

Source: https://mnemoverse.com/docs/api/python-sdk

Use pip to install the package. Requires Python 3.10 or higher.

```bash
pip install mnemoverse
```

--------------------------------

### MCP Server Integration Examples

Source: https://mnemoverse.com/docs/api/rooms

Examples of passing the room domain parameter through MCP server tools for shared context.

```json
{
  "content": "Flight to Lisbon booked for Sept 12, returning Sept 19. Hotel not booked yet.",
  "domain": "xroom:room_01J8ZQ5XK7E9GVA2M4N6P8R0TC"
}
```

```json
{
  "query": "when is the Lisbon trip?",
  "domain": "xroom:room_01J8ZQ5XK7E9GVA2M4N6P8R0TC"
}
```

--------------------------------

### Automated Claude MCP setup

Source: https://mnemoverse.com

Instruct Claude to handle the MCP server installation and API key configuration automatically.

```bash
claude "Add the @mnemoverse/mcp-memory-server MCP server with env var MNEMOVERSE_API_KEY, then ask me for my key"
```

--------------------------------

### Install A2A SDK

Source: https://mnemoverse.com/docs/library/a2a-integration-howto

Install the required A2A SDK and Uvicorn server dependencies via pip.

```bash
pip install a2a-sdk uvicorn
```

--------------------------------

### Initialize Mnemoverse in Python

Source: https://mnemoverse.com/docs/llms.txt

Install the package via pip and initialize the client using your API key.

```python
pip install mnemoverse
MnemoClient(api_key="mk_live_YOUR_KEY")
```

--------------------------------

### Initialize Mnemoverse Client

Source: https://mnemoverse.com/docs/library/rescorla-wagner-agent-memory

Setup the MnemoClient using an API key to interact with the Mnemoverse service.

```python
from mnemoverse import MnemoClient
client = MnemoClient(api_key="mk_live_YOUR_KEY")
```

--------------------------------

### Quick Start with MnemoClient

Source: https://mnemoverse.com/docs/api/python-sdk

Initialize the client and perform basic memory storage, retrieval, and feedback operations.

```python
from mnemoverse import MnemoClient

client = MnemoClient(api_key="mk_live_YOUR_KEY")

# Store a memory
result = client.write(
    "Retry with exponential backoff fixed the timeout issue",
    concepts=["retry", "backoff", "timeout"],
    domain="engineering"
)
print(f"Stored: {result.stored}, ID: {result.atom_id}")

# Query memories
memories = client.read("how to handle timeouts?", top_k=5)
for item in memories.items:
    print(f"[{item.relevance:.2f}] {item.content}")

# Report outcome — the system learns what works
client.feedback(
    atom_ids=[item.atom_id for item in memories.items],
    outcome=1.0,
    query_concepts=memories.query_concepts
)
```

--------------------------------

### Gateway-exposed tool list with namespacing

Source: https://mnemoverse.com/docs/research/mcp/federated/architecture

Example of how a gateway resolves tool name collisions by applying server-name prefixes to upstream tools.

```json
// Upstream A: "github-service" · Upstream B: "local-fs"
// Gateway-exposed tools:
[
  { "name": "github-service_read_file", "description": "Read file contents from the GitHub repository..." },
  { "name": "local-fs_read_file",       "description": "Read file contents from the local workspace..." }
]
```

--------------------------------

### Install Mnemoverse MCP Server

Source: https://mnemoverse.com/docs/llms.txt

Use this command to execute the latest version of the Mnemoverse MCP server via npx.

```bash
npx -y @mnemoverse/mcp-memory-server@latest
```

--------------------------------

### Cross-tool memory interaction example

Source: https://mnemoverse.com/docs/api/use-cases/coding-assistants

A conceptual demonstration of how memory persists when writing in Claude Code and reading in Cursor.

```text
Monday in Claude Code:
  You: "We always use feature branches, never push to main directly"
  Claude: [stores memory]

Wednesday in Cursor:
  You: "Push this change"
  Cursor: [reads memory] "Created feature branch. PR to main as usual."
```

--------------------------------

### GET /health

Source: https://mnemoverse.com/docs/api/reference

Liveness probe to check if the service process is running.

```APIDOC
## GET /health

### Description
Liveness probe. Returns 200 as long as the process is serving. Does NOT check the database, embedding model, or any downstream.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Always "ok" when the process is up.
- **database** (boolean) - Always false.
- **version** (string) - Service version.
```

--------------------------------

### GET /memory/stats

Source: https://mnemoverse.com/docs/api/reference

Retrieves memory statistics for the current tenant.

```APIDOC
## GET /memory/stats

### Description
Get memory statistics for your tenant.

### Method
GET

### Endpoint
/memory/stats

### Response
#### Success Response (200)
- **total_atoms** (int) - Total atoms stored
- **episodes** (int) - Episode-type atoms
- **prototypes** (int) - Prototype atoms (from consolidation)
- **singletons** (int) - Protected singleton atoms
- **hebbian_edges** (int) - Concept-concept association edges
- **episodic_fingerprints** (int) - Number of distinct episodic-content fingerprints across stored atoms
- **domains** (string[]) - Active domain names
- **avg_valence** (float) - Average outcome valence
- **avg_importance** (float) - Average importance score
```

--------------------------------

### Install Mnemoverse for Claude Code

Source: https://mnemoverse.com/docs/llms.txt

Use this command to add the Mnemoverse MCP server to Claude Code without requiring a manual configuration file.

```bash
claude mcp add mnemoverse -e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY -- npx -y @mnemoverse/mcp-memory-server@latest
```

--------------------------------

### GET /health/ready

Source: https://mnemoverse.com/docs/api/reference

Verifies the service can handle traffic by checking the database, memory engine, and embedding backend status.

```APIDOC
## GET /health/ready

### Description
Readiness probe. Verifies the service can actually handle traffic — database reachable, memory engine initialised, embedding backend ready. This is what the post-deploy smoke hits to confirm a Railway deploy rolled out successfully.

### Method
GET

### Endpoint
/health/ready

### Response
#### Success Response (200)
- **ready** (boolean) - true only when every sub-check passes.
- **checks.database** (boolean) - DB pool is connected and SELECT 1 succeeds.
- **checks.engine** (boolean) - MemoryEngine initialised and wired to storage.
- **checks.embedding** (boolean) - Local model loaded OR API backend responded to warm-up.
- **version** (string) - Service version.

#### Response Example
{
  "ready": true,
  "checks": {
    "database": true,
    "engine": true,
    "embedding": true
  },
  "version": "1.0.0"
}
```

--------------------------------

### Initialize and Use Mnemoverse Client

Source: https://mnemoverse.com/docs/api/use-cases/chat-extensions

Use the Python SDK to store and retrieve user context across different AI tools.

```python
from mnemoverse import MnemoClient

client = MnemoClient(api_key="mk_live_YOUR_KEY")

# Store context from a Gemini conversation
client.write(
    "User's project uses FastAPI + PostgreSQL, deployed on GCP",
    concepts=["stack", "fastapi", "gcp"]
)

# Later, in any tool — retrieve it
results = client.read("what tech stack does the user have?")
```

--------------------------------

### Initialize A2A Client and Send Message

Source: https://mnemoverse.com/docs/library/a2a-integration-howto

Demonstrates the standard workflow for resolving an agent card, configuring the client, and sending a text message.

```python
import asyncio

import httpx
from a2a.client import A2ACardResolver, ClientConfig, create_client
from a2a.helpers import new_text_message
from a2a.types.a2a_pb2 import Role, SendMessageRequest

async def main():
    async with httpx.AsyncClient() as httpx_client:
        resolver = A2ACardResolver(
            httpx_client=httpx_client,
            base_url="http://127.0.0.1:9999",
        )
        card = await resolver.get_agent_card()  # async — await it

        config = ClientConfig(streaming=False)
        client = await create_client(agent=card, client_config=config)

        message = new_text_message("hello", role=Role.ROLE_USER)
        request = SendMessageRequest(message=message)

        async for chunk in client.send_message(request):
            print(chunk)

asyncio.run(main())
```

--------------------------------

### GET /api/v1/memory/stats

Source: https://mnemoverse.com/docs/api/getting-started

Retrieves global statistics about the stored memory data.

```APIDOC
## GET /api/v1/memory/stats

### Description
Returns summary statistics for the user's memory store, including atom counts, edge counts, and average metrics.

### Method
GET

### Endpoint
https://core.mnemoverse.com/api/v1/memory/stats

### Response
#### Success Response (200)
- **total_atoms** (integer) - Total number of stored atoms.
- **hebbian_edges** (integer) - Total number of Hebbian edges.
- **domains** (array) - List of active domains.
```

--------------------------------

### Initialize and Use Mnemoverse Memory Lifecycle

Source: https://mnemoverse.com/docs/library/hebbian-memory-for-ai-agents

Demonstrates the core write, read, and feedback loop using the MnemoClient. Requires an active API key to store memories, perform associative queries, and report outcomes for system learning.

```python
from mnemoverse import MnemoClient
client = MnemoClient(api_key="mk_live_YOUR_KEY")

# Store a memory, with the concepts it should associate
client.write(
    "Retry with exponential backoff fixed the timeout issue",
    concepts=["retry", "backoff", "timeout"],
)

# Query — Hebbian associations expand "timeout" → "backoff", "retry"
memories = client.read("how to handle timeouts?")

# Report the outcome — the system learns what works
client.feedback(
    atom_ids=[item.atom_id for item in memories.items],
    outcome=1.0,  # -1.0 (failure) to +1.0 (success)
    query_concepts=memories.query_concepts,
)
```

--------------------------------

### GET /api/v1/memory/stats

Source: https://mnemoverse.com/docs/platform/multi-tenant

Retrieves statistics including a list of active domains (tenants).

```APIDOC
## GET /api/v1/memory/stats

### Description
Retrieves statistics about memory usage, including a list of unique domains (tenants).

### Method
GET

### Endpoint
https://core.mnemoverse.com/api/v1/memory/stats

### Response
#### Success Response (200)
- **domains** (array) - A list of unique tenant domains.
```

--------------------------------

### GET /memory/stats

Source: https://mnemoverse.com/docs/openapi-gpt.yaml

Retrieve statistics regarding the current state of the memory system.

```APIDOC
## GET /memory/stats

### Description
Get memory statistics — total memories stored, domains, association count, average quality scores. Useful for understanding memory state.

### Method
GET

### Endpoint
/memory/stats
```

--------------------------------

### Get Memory Statistics

Source: https://mnemoverse.com/docs/api/python-sdk

Retrieve aggregate statistics about the stored memory database.

```python
stats = client.stats()
# stats.total_atoms: int
# stats.hebbian_edges: int
# stats.avg_valence: float
# stats.domains: list[str]
```

--------------------------------

### Configure Manual MCP Server for Editors

Source: https://mnemoverse.com/docs/api/editors

Manual configuration using an API key for Cursor, VS Code, and Windsurf. Ensure the editor is restarted after applying these changes.

```json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": [
        "-y",
        "@mnemoverse/mcp-memory-server@latest"
      ],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY",
        "MNEMOVERSE_API_URL": "https://core.mnemoverse.com/api/v1"
      }
    }
  }
}
```

```json
{
  "servers": {
    "mnemoverse": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@mnemoverse/mcp-memory-server@latest"
      ],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY",
        "MNEMOVERSE_API_URL": "https://core.mnemoverse.com/api/v1"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": [
        "-y",
        "@mnemoverse/mcp-memory-server@latest"
      ],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY",
        "MNEMOVERSE_API_URL": "https://core.mnemoverse.com/api/v1"
      }
    }
  }
}
```

--------------------------------

### Retrieve Memory Statistics Endpoint Definition

Source: https://mnemoverse.com/docs/openapi-gpt.yaml

Defines the GET endpoint for fetching aggregate memory metrics.

```yaml
  /memory/stats:
    get:
      operationId: getMemoryStats
      summary: Memory statistics
      description: >
        Get memory statistics — total memories stored, domains, association count,
        average quality scores. Useful for understanding memory state.
      responses:
        '200':
          description: Statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResponse'
```

--------------------------------

### Configure MCP Server

Source: https://mnemoverse.com/docs/library/memory-mcp

A minimal configuration template for adding an MCP server to a client.

```json
{
  "mcpServers": {
    "memory": {
      "command": "your-memory-server-command",
      "args": ["your-server-args"]
    }
  }
}
```

```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": { "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY" }
    }
  }
}
```

--------------------------------

### Minimal Agent Card Example

Source: https://mnemoverse.com/docs/library/a2a-agent-card

An illustrative JSON object representing a support-triage agent, adhering to the A2A specification.

```json
{
  "protocolVersion": "0.3.0",
  "name": "Acme Support Triage",
  "description": "Classifies inbound support tickets and drafts a first reply.",
  "url": "https://agents.acme.com/support-triage",
  "provider": { "organization": "Acme, Inc.", "url": "https://acme.com" },
  "version": "1.4.0",
  "documentationUrl": "https://acme.com/agents/support-triage",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": false
  },
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["application/json"],
  "skills": [
    {
      "id": "triage-ticket",
      "name": "Triage a support ticket",
      "description": "Assigns a category, priority, and suggested owner to a ticket.",
      "tags": ["support", "classification"],
      "examples": ["I was charged twice this month."],
      "inputModes": ["text/plain"],
      "outputModes": ["application/json"]
    }
  ],
  "securitySchemes": {
    "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
  },
  "security": [{ "bearer": [] }]
}
```

--------------------------------

### Configure MCP Servers in Cursor and Windsurf

Source: https://mnemoverse.com/docs/api/remote-mcp-server

Add the Mnemoverse server to the respective configuration files for Cursor and Windsurf.

```json
{ "mcpServers": { "mnemoverse": { "url": "https://mcp.mnemoverse.com/mcp" } } }
```

--------------------------------

### Configure Cursor for Mnemoverse

Source: https://mnemoverse.com/docs/api/agent-setup

Create a .cursor/mcp.json file in the project root to register the remote MCP server. A restart of the editor is required after configuration.

```json
{
  "mcpServers": {
    "mnemoverse": {
      "url": "https://mcp.mnemoverse.com/mcp"
    }
  }
}
```

--------------------------------

### Check Service Readiness

Source: https://mnemoverse.com/docs/api/reference

Use this endpoint for Kubernetes or Railway readiness probes to verify the service is fully initialized.

```bash
curl https://core.mnemoverse.com/api/v1/health/ready
# {"ready":true,"checks":{"database":true,"engine":true,"embedding":true},"version":"1.0.0"}
```

--------------------------------

### Visualize Platform Architecture

Source: https://mnemoverse.com/docs/platform/overview

A structural representation of how a single API key manages multiple isolated tenant domains.

```text
Your API Key
├── domain: "tenant:alice"     ← Alice's memories (isolated)
├── domain: "tenant:bob"       ← Bob's memories (isolated)
├── domain: "tenant:acme"      ← Acme Corp memories (isolated)
└── domain: "shared:knowledge" ← Your product's knowledge base
```

--------------------------------

### Write and Read Agent Memory Domains

Source: https://mnemoverse.com/docs/platform/multi-tenant

Demonstrates writing to private agent domains and shared project domains, followed by reading from those specific contexts.

```python
client.write("Identified 3 relevant APIs", domain="agent:researcher")
client.write("Draft ready for review", domain="agent:writer")

# Shared project context — all agents can read
client.write("Deadline is Friday", domain="project:acme")

# Agent reads own memory + shared context
own = client.read("what have I found?", domain="agent:researcher")
shared = client.read("project deadlines", domain="project:acme")
```

--------------------------------

### Configure MCP for VS Code

Source: https://mnemoverse.com/docs/api/agent-setup

Create the .vscode/mcp.json file in your project root. Requires an API key.

```json
{
  "servers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_USER_KEY"
      }
    }
  }
}
```

--------------------------------

### Claude Desktop Local Configuration

Source: https://mnemoverse.com/docs/api/claude-apps

Configuration for the local stdio server in claude_desktop_config.json, requiring an API key.

```json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": [
        "-y",
        "@mnemoverse/mcp-memory-server@latest"
      ],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY",
        "MNEMOVERSE_API_URL": "https://core.mnemoverse.com/api/v1"
      }
    }
  }
}
```

--------------------------------

### Define an Agent Card JSON structure

Source: https://mnemoverse.com/docs/library/a2a-protocol-explained

Illustrative example of an Agent Card JSON document used for advertising agent identity, capabilities, and endpoints.

```json
{
  "name": "Portfolio Analyzer Agent",
  "description": "Analyzes investment portfolios and generates risk reports.",
  "endpoints": [
    {
      "protocol": "jsonrpc-http",
      "uri": "https://api.example.com/a2a/v1"
    }
  ],
  "capabilities": [
    {
      "name": "risk_assessment",
      "description": "Calculates Value at Risk (VaR) for a given asset list."
    }
  ],
  "authentication": {
    "schemes": ["bearer"]
  }
}
```

--------------------------------

### Implement Shared Memory with MnemoClient

Source: https://mnemoverse.com/docs/library/shared-memory-for-multi-agent-systems

Demonstrates writing to private and shared domains and reading from a shared project domain using the Mnemoverse SDK.

```python
from mnemoverse import MnemoClient

client = MnemoClient(api_key="...")

# Private working memory for the researcher agent.
client.write(
    "The customer prefers short implementation notes with explicit tradeoffs.",
    domain="agent:researcher",
)

# Shared project context for other participating agents.
client.write(
    "The API integration should prioritize explicit error handling.",
    domain="project:acme",
)

# A developer agent can read from the shared project domain.
results = client.read(
    query="What project constraints should guide the integration?",
    domain="project:acme",
)
```

--------------------------------

### Configure MCP Client

Source: https://mnemoverse.com/docs/llms.txt

Standard JSON configuration for MCP-compatible clients. Ensure the MNEMOVERSE_API_KEY is replaced with your actual live key.

```json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": { "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY" }
    }
  }
}
```

--------------------------------

### Configure MCP for Cursor

Source: https://mnemoverse.com/docs/api/agent-setup

Create or update the .cursor/mcp.json file in your project root to enable the memory server.

```json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_USER_KEY"
      }
    }
  }
}
```

--------------------------------

### Configure MnemoClient

Source: https://mnemoverse.com/docs/api/python-sdk

Customize client settings such as base URL, timeout, and retry logic during initialization.

```python
client = MnemoClient(
    api_key="mk_live_YOUR_KEY",
    base_url="https://core.mnemoverse.com",  # default
    timeout=10.0,                            # seconds, default: 10
    max_retries=3,                           # default: 3
)
```

--------------------------------

### Mnemoverse memory lifecycle workflow

Source: https://mnemoverse.com/docs/api/overview

A high-level overview of the memory processing pipeline from initial write to consolidation.

```text
1. WRITE  →  Importance gate filters noise  →  Stored with semantic embedding
2. READ   →  Hebbian expansion  →  Valence-boosted ranking  →  Results
3. FEEDBACK  →  Outcome updates valence  →  Strengthens associations
4. CONSOLIDATE  →  HDBSCAN clusters similar  →  Prototypes + singletons
```

--------------------------------

### Basic File-Based Memory Pattern

Source: https://mnemoverse.com/docs/research/ai-agent-memory-crisis

The standard workflow for agent memory involving file persistence and context re-injection.

```text
1. Write useful information to a file
2. Re-read that file later into prompt context
3. Hope the model uses the right parts
```

--------------------------------

### Deterministic Context Layout

Source: https://mnemoverse.com/docs/research/agents/deterministic-vs-llm-context-assembly

A conceptual layout for organizing context to maximize KV-cache hits by placing stable content before volatile, request-specific data.

```text
[stable system policy]
[stable tool schemas]
[stable memory contract]
[cache breakpoint]
[request-specific retrieved items]
[latest user turn]
```

--------------------------------

### Implement an ordered context eviction policy

Source: https://mnemoverse.com/docs/research/agents/context-budgeting

A tiered approach to managing context overflow by sequentially clearing tool results, compacting dialogue, reducing retrieval, offloading state, and requesting scope reduction.

```python
if projected_context > budget:
  clear_old_tool_results(keep_required=true)

if projected_context > budget:
  compact_dialogue(
    preserve=[
      "user goal",
      "architectural decisions",
      "constraints",
      "unresolved bugs",
      "open tasks"
    ],
    discard=[
      "redundant tool outputs",
      "repeated assistant phrasing",
      "obsolete intermediate observations"
    ]
  )

if projected_context > budget:
  reduce_retrieval_to_ranked_cap(
    preserve_citations=true,
    place_best_evidence_at_zone_edges=true
  )

if projected_context > budget:
  offload_long_term_state_to_memory()

if projected_context > budget:
  ask_for_scope_reduction_or_continue_in_chunks()
```

--------------------------------

### Reading Files via Shell Commands

Source: https://mnemoverse.com/docs/library/why-ai-agents-nag-about-secrets

Demonstrates how an agent with shell access can bypass ignore rules by executing standard system commands.

```bash
cat .env
```

--------------------------------

### Custom GPT System Instructions

Source: https://mnemoverse.com/docs/api/chatgpt

The required system prompt to enable persistent memory and define rules for reading, writing, and providing feedback to Mnemoverse.

```text
You have persistent long-term memory via Mnemoverse.

RULES:
1. BEFORE answering any question about preferences, past decisions, project 
   setup, people, or anything that might have been discussed before — call 
   readMemory first.
2. When the user shares a preference, makes a decision, teaches you something, 
   or tells you something important — call writeMemory immediately. Don't wait 
   to be asked.
3. After using memories to answer a question, call giveFeedback to report 
   whether they were helpful (1.0) or not (-1.0).
4. Your memory persists across sessions and across tools. What you learn here 
   is available in Claude Code, Cursor, and everywhere else.

WHAT TO REMEMBER:
- Preferences ("I prefer Railway over Heroku")
- Decisions ("We chose PostgreSQL for this project")
- Lessons ("Exponential backoff fixed the timeout issue")
- People ("Alice owns the design system")
- Project context ("Deploy target is staging.example.com")

WHAT NOT TO REMEMBER:
- Trivial small talk
- Temporary context ("open this file")
- Information already in the current conversation
```

--------------------------------

### Load a BLEU metric module

Source: https://mnemoverse.com/docs/research/evaluation/huggingface-evaluate-deepdive

Initializes the BLEU metric module using the evaluate library's load function.

```python
import evaluate
bleu = evaluate.load("bleu")
```

--------------------------------

### Read with Tenant Fallback

Source: https://mnemoverse.com/docs/platform/multi-tenant

Query tenant-specific memory first, falling back to shared knowledge if no results are found.

```python
tenant_memories = client.read(query, domain="tenant:acme-corp")

if not tenant_memories.items:
    # Fall back to shared product knowledge
    shared_memories = client.read(query, domain="shared:product-docs")
```

--------------------------------

### Check System Statistics

Source: https://mnemoverse.com/docs/api/getting-started

Retrieves current system metrics including total atoms, Hebbian edges, and average valence.

```bash
curl https://core.mnemoverse.com/api/v1/memory/stats \
  -H "X-Api-Key: mk_live_YOUR_KEY"
```

```json
{
  "total_atoms": 1,
  "episodes": 1,
  "prototypes": 0,
  "singletons": 0,
  "hebbian_edges": 3,
  "episodic_fingerprints": 0,
  "domains": ["engineering"],
  "avg_valence": 0.8,
  "avg_importance": 0.85
}
```

--------------------------------

### Configure MCP Server for Tenants

Source: https://mnemoverse.com/docs/platform/multi-tenant

Set the default domain via environment variables in the MCP server configuration.

```json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server"],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY",
        "MNEMOVERSE_DEFAULT_DOMAIN": "tenant:acme-corp"
      }
    }
  }
}
```

--------------------------------

### Mnemoverse Standing Instruction Block

Source: https://mnemoverse.com/docs/api/agent-memory

Add this markdown block to your project's agent configuration file to establish a persistent habit of using memory tools.

```markdown
## Mnemoverse Memory — always use it

You have persistent memory across sessions via the Mnemoverse MCP tools
(memory_read, memory_write, memory_feedback). Treat it as required, not optional:

- Recall first. At the start of every task — and whenever the user references a
  past decision, preference, or fact — call memory_read BEFORE answering. Never
  assume a cold start.
- Save as you go. Call memory_write whenever the user states a preference, makes
  a decision, corrects you, or shares a durable fact (stack, conventions, people,
  gotchas) — even without being asked.
- Close the loop. After a recalled memory helped or misled, call memory_feedback
  so retrieval improves over time.

Never tell the user "I don't have memory of that" without first calling memory_read.
```

--------------------------------

### Configure MCP Server in VS Code

Source: https://mnemoverse.com/docs/api/remote-mcp-server

Add the Mnemoverse server to the .vscode/mcp.json file, ensuring the type is set to http.

```json
{ "servers": { "mnemoverse": { "type": "http", "url": "https://mcp.mnemoverse.com/mcp" } } }
```

--------------------------------

### Monitor Tenant Statistics

Source: https://mnemoverse.com/docs/platform/multi-tenant

Retrieve memory statistics to view the list of active domains.

```bash
curl https://core.mnemoverse.com/api/v1/memory/stats \
  -H "X-Api-Key: mk_live_YOUR_KEY"
```

--------------------------------

### Integrate with LangChain

Source: https://mnemoverse.com/docs/api/python-sdk

Create custom tools for LangChain agents to store and recall memories.

```python
from langchain.tools import tool
from mnemoverse import MnemoClient

memory = MnemoClient(api_key="mk_live_YOUR_KEY")

@tool
def remember(content: str, concepts: list[str]) -> str:
    """Store a memory for future reference."""
    result = memory.write(content, concepts=concepts)
    return f"Stored: {result.stored}, importance: {result.importance:.2f}"

@tool
def recall(query: str) -> str:
    """Search memories for relevant information."""
    results = memory.read(query, top_k=5)
    return "\n".join(f"- {item.content}" for item in results.items)
```

--------------------------------

### Run DeepEval tests via CLI

Source: https://mnemoverse.com/docs/research/evaluation/deepeval-framework-deepdive

Execute the test suite using the deepeval command-line interface.

```bash
deepeval test run test_refund.py
```

--------------------------------

### Connect Claude Code to Mnemoverse

Source: https://mnemoverse.com/docs/api/remote-mcp-server

Use the CLI command to add the Mnemoverse MCP server to Claude Code.

```bash
claude mcp add --transport http mnemoverse https://mcp.mnemoverse.com/mcp
```

--------------------------------

### Define context budget tiers in YAML

Source: https://mnemoverse.com/docs/research/agents/context-budgeting

Configuration structure for defining minimum and maximum token budgets alongside protection tiers for various agent memory zones.

```yaml
context_budget:
  system:
    min: fixed
    max: fixed
    tier: protected
  tool_schemas:
    min: selected_tools_only
    max: turn_relevant_tools
    tier: mostly_protected
  stable_prefix:
    min: committed
    max: committed
    tier: non_reallocatable
  retrieval:
    min: evidence_floor
    max: ranked_cap
    tier: compactable
  history:
    min: recent_turns_plus_summary
    max: bounded
    tier: compactable
  tool_outputs:
    min: latest_required_observations
    max: small
    tier: clearable
  output_buffer:
    min: answer_floor
    max: task_dependent
    tier: protected
```

--------------------------------

### POST /memory/write

Source: https://mnemoverse.com/docs/llms.txt

Stores a preference, decision, or lesson in the specified domain.

```APIDOC
## POST /memory/write

### Description
Stores a preference, decision, or lesson. To write to a shared room, pass the room address `xroom:<room_id>` in the `domain` field.

### Method
POST

### Endpoint
/memory/write

### Request Body
- **content** (string) - Required - The memory content to store.
- **concepts** (array) - Optional - Associated concepts.
- **domain** (string) - Optional - The domain or room address (e.g., `xroom:<room_id>`).
```

--------------------------------

### Check Service Liveness

Source: https://mnemoverse.com/docs/api/reference

Use this endpoint for load-balancer liveness probes or uptime monitoring. It does not perform database checks and is safe to call at high frequency.

```bash
curl https://core.mnemoverse.com/api/v1/health
# {"status":"ok","database":false,"version":"1.0.0"}
```

--------------------------------

### Mnemoverse Integration Architecture

Source: https://mnemoverse.com/docs/api/chatgpt

A visual representation of how Mnemoverse memory is shared across various tools including ChatGPT.

```text
                    ┌── Claude Code (MCP)
                    ├── Cursor (MCP)
   Mnemoverse API ──├── VS Code (MCP)
   (one memory)     ├── ChatGPT (Actions) ← you are here
                    ├── Python SDK
                    └── REST API
```

--------------------------------

### POST /memory/write_batch

Source: https://mnemoverse.com/docs/api/rooms

Writes a batch of memory items to the system, supporting mixed room and private domains.

```APIDOC
## POST /memory/write_batch

### Description
Writes a batch of memory items. Each item can be assigned to a specific room or private domain.

### Method
POST

### Endpoint
https://core.mnemoverse.com/api/v1/memory/write_batch

### Request Body
- **items** (array) - Required - List of memory items to store.

### Response
#### Success Response (200)
- **total_count** (integer) - Total items processed.
- **stored_count** (integer) - Total items successfully stored.
- **results** (array) - Detailed status for each item.
```

--------------------------------

### Integrate Memory Tools into LangChain Agent

Source: https://mnemoverse.com/docs/api/use-cases/agent-frameworks

Add the defined remember and recall tools to a LangChain tool-calling agent.

```python
from langchain.agents import create_tool_calling_agent

agent = create_tool_calling_agent(
    llm=llm,
    tools=[remember, recall, ...your_other_tools],
    prompt=prompt  # Include: "Always check recall() before starting tasks"
)
```

--------------------------------

### Use Async Client

Source: https://mnemoverse.com/docs/api/python-sdk

Utilize the asynchronous client for non-blocking operations in frameworks like FastAPI or Discord bots.

```python
from mnemoverse import AsyncMnemoClient

client = AsyncMnemoClient(api_key="mk_live_YOUR_KEY")

result = await client.write("async memory", concepts=["async"])
memories = await client.read("what about async?")
await client.feedback(atom_ids=[...], outcome=1.0)
```

--------------------------------

### Check Memory Status with memory_stats

Source: https://mnemoverse.com/docs/api/claude

Retrieve summary statistics about the current memory store.

```text
Claude: [calls memory_stats]
→ Memories: 1,250 (500 episodes, 450 prototypes)
  Associations: 8,500 Hebbian edges
  Domains: engineering, user:alice, project:acme
  Avg quality: valence 0.65, importance 0.72
```

--------------------------------

### POST /memory/feedback

Source: https://mnemoverse.com/docs/api/rooms

Provides feedback on specific memory items to mutate ranking weights within a room.

```APIDOC
## POST /memory/feedback

### Description
Updates ranking weights for memory items based on feedback, requiring read_write membership.

### Method
POST

### Endpoint
https://core.mnemoverse.com/api/v1/memory/feedback

### Request Body
- **atom_ids** (array) - Required - List of atom IDs to provide feedback on.
- **outcome** (float) - Required - The feedback outcome value.
- **query_concepts** (array) - Optional - Concepts associated with the feedback.
- **domain** (string) - Required - The room domain identifier.

### Response
#### Success Response (200)
- **updated_count** (integer) - Number of items updated.
- **avg_valence** (float) - Average valence score.
- **coactivation_edges** (integer) - Number of coactivation edges created.
- **feedback_time_ms** (float) - Time taken to process feedback.
```

--------------------------------

### POST /memory/write

Source: https://mnemoverse.com/docs/api/rooms

Writes a single memory item to a domain.

```APIDOC
## POST /memory/write

### Description
Attempts to write a single memory item to a domain. Fails with 403 if the API key lacks write permissions.

### Method
POST

### Endpoint
https://core.mnemoverse.com/api/v1/memory/write

### Request Body
- **content** (string) - Required - The content to store.
- **domain** (string) - Required - The target domain or room.
```

--------------------------------

### Handle Read-Only Access Errors

Source: https://mnemoverse.com/docs/api/rooms

Demonstrates a failed write attempt when using a key with only read scope.

```bash
curl -X POST https://core.mnemoverse.com/api/v1/memory/write \
  -H "X-Api-Key: mk_live_READONLY_CONSUMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Consumers should not be able to add this.",
    "domain": "xroom:room_01J8ZQ5XK7E9GVA2M4N6P8R0TC"
  }'
```

```json
{
  "code": "FORBIDDEN",
  "message": "Read-only membership cannot write to this room",
  "requestId": "...",
  "retryable": false,
  "details": null
}
```

--------------------------------

### Handle A2A Task with Memory Scoping

Source: https://mnemoverse.com/docs/library/a2a-integration-howto

Demonstrates a pattern for delegating tasks while maintaining explicit, domain-scoped memory access.

```python
async def handle_a2a_task(task):
    domain = task.metadata["domain"]  # explicit scope, e.g. "project:acme"

    prior_context = memory_read(
        domain=domain,
        query="What should I know before handling this task?",
    )

    artifact = await do_agent_work(task, prior_context)

    memory_write(
        domain=domain,
        content="Finding from the delegated task...",
        source="a2a-task",
    )

    return artifact
```

--------------------------------

### POST /memory/write

Source: https://mnemoverse.com/docs/api/reference

Stores a single memory atom in the system.

```APIDOC
## POST /memory/write

### Description
Store a single memory atom.

### Method
POST

### Endpoint
/memory/write

### Parameters
#### Request Body
- **content** (string) - Required - The insight, pattern, or lesson to remember (1-10,000 chars)
- **concepts** (string[]) - Optional - Key concepts for Hebbian associations
- **domain** (string) - Optional - Namespace: general, user:X, project:Z (default: general)
- **metadata** (object) - Optional - Arbitrary key-value metadata
- **external_ref** (string) - Optional - Client-provided unique reference for idempotent writes

### Response
#### Success Response (200)
- **stored** (boolean) - True if the atom passed the importance gate
- **atom_id** (UUID) - UUID of the stored atom, or null if filtered
- **importance** (float) - Computed importance score [0, 1]
- **reason** (string) - Why stored or filtered
```

--------------------------------

### BLEU Reference Format Comparison

Source: https://mnemoverse.com/docs/research/evaluation/huggingface-evaluate-deepdive

Demonstrates the incorrect flat list format versus the correct list-of-lists format for BLEU references.

```python
# WRONG — references as a flat list of strings
bleu.compute(predictions=["hello there general kenobi"],
             references=["hello there general kenobi"])   # error or wrong score

# RIGHT — references as a list of *lists* of strings
bleu.compute(predictions=["hello there general kenobi"],
             references=[["hello there general kenobi", "hello there!"]])
```

--------------------------------

### Score a Classifier with Accuracy and F1

Source: https://mnemoverse.com/docs/research/evaluation/huggingface-evaluate-deepdive

Shows how to load and compute classification metrics using flat lists of labels.

```python
accuracy = evaluate.load("accuracy")
accuracy.compute(predictions=[0, 1, 1, 0], references=[0, 1, 0, 0])
# {'accuracy': 0.75}

f1 = evaluate.load("f1")
f1.compute(predictions=[0, 1, 1], references=[0, 1, 0], average="macro")
```

--------------------------------

### Define an Opaque Tool Call

Source: https://mnemoverse.com/docs/library/credential-llm-never-sees

Use an opaque selector like 'ticketing_prod' in the tool arguments instead of a direct secret path or credential.

```yaml
tool_call:
  name: create_ticket
  arguments:
    customer_id: "cus_123"
    integration: "ticketing_prod"   # an opaque selector, not a secret path
```

--------------------------------

### POST /api/v1/memory/write

Source: https://mnemoverse.com/docs/api/rooms

Writes a new memory atom to a specific room domain.

```APIDOC
## POST /api/v1/memory/write

### Description
Writes findings to a shared room address. This allows different agents or users to contribute to the same memory pool.

### Method
POST

### Endpoint
https://core.mnemoverse.com/api/v1/memory/write

### Request Body
- **content** (string) - Required - The memory content (1-10,000 characters).
- **concepts** (array) - Optional - List of concepts associated with the memory.
- **domain** (string) - Required - The room address (e.g., "xroom:room_...").
- **metadata** (object) - Optional - Additional metadata.
- **fingerprint** (string) - Optional - Unique identifier for deduplication.
- **external_ref** (string) - Optional - External reference identifier.

### Request Example
{
  "content": "Staging deploys fail when REDIS_URL is unset.",
  "concepts": ["staging", "redis", "deploy"],
  "domain": "xroom:room_01J8ZQ5XK7E9GVA2M4N6P8R0TC"
}

### Response
#### Success Response (200)
- **stored** (boolean) - Confirmation of storage.
- **atom_id** (string) - Unique ID of the stored atom.
- **importance** (number) - Calculated importance score.
- **reason** (string) - Reason for the importance score.
```

--------------------------------

### Authenticate API Requests

Source: https://mnemoverse.com/docs/api/reference

Use either the X-Api-Key header or an Authorization Bearer token to authenticate requests to the Mnemoverse API.

```bash
# Option 1: X-Api-Key header (recommended)
curl -H "X-Api-Key: mk_live_YOUR_KEY" ...

# Option 2: Bearer token
curl -H "Authorization: Bearer mk_live_YOUR_KEY" ...
```

--------------------------------

### Exporting API Keys as Environment Variables

Source: https://mnemoverse.com/docs/library/why-ai-agents-nag-about-secrets

Use this pattern to keep secrets out of application source code and prevent accidental commits to version control.

```bash
export OPENAI_API_KEY="..."
```

--------------------------------

### Visualize A2A persistent memory workflow

Source: https://mnemoverse.com/docs/library/a2a-integration-howto

Sequence diagram illustrating how agents interact with a shared memory domain during task delegation.

```text
┌────────────────────┐                          ┌────────────────────┐
│    Client Agent    │                          │  Delegated Agent   │
└─────────┬──────────┘                          └─────────┬──────────┘
          │                                               │
          │  1. Delegate task (A2A JSON-RPC, carries      │
          │     domain="project:acme")                    │
          ├──────────────────────────────────────────────>│
          │                                               │  2. memory_read(domain)
          │                                               │     → prior context
          │                                               │
          │                                               │  3. Do the work
          │                                               │
          │                                               │  4. memory_write(domain)
          │                                               │     → findings persist
          │  5. Return Artifact (A2A JSON-RPC)            │
          │<──────────────────────────────────────────────┤
          │                                               │
```

--------------------------------

### POST /api/v1/memory/read

Source: https://mnemoverse.com/docs/api/rooms

Queries memory atoms from a specific room domain.

```APIDOC
## POST /api/v1/memory/read

### Description
Retrieves memory atoms from a shared room domain. Retrieval uses relevance ranking and concept expansion.

### Method
POST

### Endpoint
https://core.mnemoverse.com/api/v1/memory/read

### Request Body
- **query** (string) - Required - The search query.
- **domain** (string) - Required - The room address (e.g., "xroom:room_...").
- **top_k** (integer) - Optional - Number of results to return.

### Request Example
{
  "query": "why do staging deploys time out?",
  "domain": "xroom:room_01J8ZQ5XK7E9GVA2M4N6P8R0TC",
  "top_k": 5
}

### Response
#### Success Response (200)
- **items** (array) - List of retrieved memory atoms.
- **episodic_hit** (boolean) - Whether an episodic memory was hit.
- **query_concepts** (array) - Concepts extracted from the query.
- **expanded_concepts** (array) - Concepts expanded via association.
- **search_time_ms** (number) - Time taken for the search.
```

--------------------------------

### POST /memory/write-batch

Source: https://mnemoverse.com/docs/api/reference

Stores up to 500 memory atoms in a single request.

```APIDOC
## POST /memory/write-batch

### Description
Store up to 500 atoms in one request.

### Method
POST

### Endpoint
/memory/write-batch

### Parameters
#### Request Body
- **items** (WriteRequest[]) - Required - Array of write requests (1-500)

### Response
#### Success Response (200)
- **total_count** (int) - Total atoms processed
- **stored_count** (int) - Atoms that passed importance gate
- **results** (object[]) - Per-atom results with index, stored, atom_id, importance, error
```

--------------------------------

### POST /memory/read

Source: https://mnemoverse.com/docs/openapi-gpt.yaml

Search the user's memory by natural language query. This should be called before answering questions about past discussions or preferences.

```APIDOC
## POST /memory/read

### Description
Search the user's memory by natural language query. ALWAYS call this BEFORE answering questions about preferences, past decisions, project setup, or anything discussed before.

### Method
POST

### Endpoint
/memory/read

### Request Body
- **ReadRequest** (object) - Required - The search query parameters.
```

--------------------------------

### POST /api/v1/memory/write

Source: https://mnemoverse.com/docs/api/getting-started

Stores a new memory in the Mnemoverse system. The system automatically filters noise based on importance.

```APIDOC
## POST /api/v1/memory/write

### Description
Stores a new memory atom. The system evaluates the importance of the content and may reject it if it is too similar to existing data.

### Method
POST

### Endpoint
https://core.mnemoverse.com/api/v1/memory/write

### Request Body
- **content** (string) - Required - The text content of the memory.
- **concepts** (array) - Optional - A list of concepts associated with the memory.
- **domain** (string) - Optional - The domain category for the memory.

### Response
#### Success Response (200)
- **stored** (boolean) - Indicates if the memory was successfully stored.
- **atom_id** (string) - Unique identifier for the stored memory.
- **importance** (number) - Calculated importance score.
- **reason** (string) - Explanation for the importance score.
```

--------------------------------

### Defining Git Ignore Rules

Source: https://mnemoverse.com/docs/library/why-ai-agents-nag-about-secrets

Configure git to ignore sensitive files like .env to prevent them from being tracked in source control.

```text
.env
```

--------------------------------

### Store Memory with memory_write

Source: https://mnemoverse.com/docs/api/claude

Claude uses this tool to persist preferences, lessons, or decisions into long-term memory.

```text
You: "I prefer Tailwind over CSS modules"
Claude: [calls memory_write]
    content: "User prefers Tailwind CSS over CSS modules for styling"
    concepts: ["tailwind", "css", "styling", "preferences"]
→ Stored (importance: 0.82)
```

--------------------------------

### Declare Streaming Capability

Source: https://mnemoverse.com/docs/library/a2a-integration-howto

Required JSON configuration within the Agent Card to enable SSE streaming support.

```json
{
  "capabilities": {
    "streaming": true
  }
}
```