# Mesh Memory

> Self-hosted semantic memory for AI agents via MCP. Save worklogs, decisions, and notes, then recall them across sessions by meaning, not keyword. Postgres + pgvector with auto-tagging.

- Skill: `ranbot-ai/mesh-memory` (Agent Skill)
- Install (CLI): `npx skillmds add ranbot-ai/mesh-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ranbot-ai/mesh-memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ranbot-ai (https://skillmd.com/u/ranbot-ai)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/ranbot-ai/mesh-memory

---



# Mesh Memory

Mesh Memory is a self-hosted semantic memory service with a built-in MCP server. It stores documents (worklogs, decisions, notes, research) in PostgreSQL with pgvector and retrieves them by meaning, so a query like "what database did we pick?" surfaces a saved note that says "chose Redis for caching" even with zero keyword overlap. Embeddings are generated locally with `multilingual-e5-base` (768 dimensions); the core flow requires no external API keys.

Use this skill when an agent needs persistent memory across sessions: saving its own work, recalling prior decisions, or building a project knowledge base shared between multiple agents.

## When to Use This Skill

- Saving a session worklog, decision, or research note so a later session can find it.
- Recalling past work by topic when you do not remember the exact words you used.
- Sharing a long-lived knowledge base across multiple agents, terminals, or teammates.
- Organizing context by role or project through workspaces (one workspace per role/project).
- Looking up structured tags (e.g. all `type:decision` entries from one project).

## Prerequisites

- A running Mesh Memory instance reachable from the MCP server. Local Docker is the common path -- `docker compose up -d` in the upstream repo brings it up; see https://github.com/dklymentiev/mesh-memory for the full Quick Start.
- The MCP server (`mcp_server.py`) registered with your client (Claude Code, Cursor, Claude Desktop, or any other MCP-aware agent).
- `MESH_API_URL` pointing at the running instance (default: `http://localhost:8000`).

## Setup

Register the MCP server in your client configuration:

```json
{
  "mcpServers": {
    "mesh": {
      "command": "python3",
      "args": ["/path/to/mesh-memory/mcp_server.py"],
      "env": {
        "MESH_API_URL": "http://localhost:8000"
      }
    }
  }
}
```

When the server is reachable, the 13 tools listed below become available.

## MCP Tools

| Tool | Purpose |
|------|---------|
| `mesh_focus` | Switch the active workspace (optionally prefetch recent docs). |
| `mesh_add` | Save a document with optional tags. Auto-adds `date:YYYY-MM-DD` and `source:`. |
| `mesh_update` | Update content, tags, or pinned status of an existing document. |
| `mesh_delete` | Delete a document by GUID. |
| `mesh_get` | Fetch a single document by GUID. |
| `mesh_search` | Semantic search by query, optionally across multiple workspaces with weights. |
| `mesh_bytag` | List documents that match one or more tags (AND logic). |
| `mesh_recent` | List most recently created documents, optionally filtered by `type:` tag. |
| `mesh_projects` | List per-project document counts (uses `guid:` tag as project marker). |
| `mesh_tags` | List existing tags with counts; optional prefix filter. |
| `mesh_versions` | Show the version chain of a document (similarity-linked revisions). |
| `mesh_stats` | Memory statistics for the active workspace. |
| `mesh_schema` | Show the tag schema (recognized prefixes and types). |

## Workflows

### Save a session worklog

After completing work, persist it for future sessions:

```
mesh_add(
  content="Investigated 502s on the checkout flow. Root cause: missing CORS header on the cart API. Fix shipped in commit abc123.",
  tags="type:worklog,topic:checkout,date:2026-05-23",
  workspace="developer"
)
```

`date:` and `source:` are added automatically when omitted. Type and topic tags are inferred from nearest neighbors after the embedding completes (5-10 seed documents required before inference kicks in).

### Recall past work by meaning

Search across sessions for related context, even with different vocabulary:

```
mesh_search(query="checkout was failing for some users", limit=5, workspace="developer")
```

The query shares no keywords with the original note ("502s", "CORS"), but the embedding-based search surfaces it.

### Switch role / context

For a multi-role agent, switch the active workspace at the start of a session:

```
mesh_focus(workspace="sysadmin", prefetch=true, limit=5)
```

Subsequent calls default to that workspace. Pin a role-prompt document at the top of each workspace so the agent re-orients on every prefetch.

### Cross-workspace search with weights

To pull context from related domains without diluting the primary signal:

```
mesh_search(
  query="nginx rate limit recipe",
  workspaces={"sysadmin": 0.7, "security": 0.2, "developer": 0.1},
  limit=10
)
```

Results are merged across workspaces and re-scored by workspace weight.

### Structured lookups by tag

When you need an exact filter rather than semantic similarity:

```
mesh_bytag(tags="type:decision,status:active,guid:my-project", limit=20)
```

## Tag Conventions

Mesh accepts arbitrary tags. The recommended prefixes (used by auto-inference and surfaced by `mesh_schema`):

| Prefix | Meaning |
|--------|---------|
| `type:worklog` | Completed work; the most common type. |
| `type:note` | Quick notes, observations. |
| `type:decision` | Architecture