Build Persistent Semantic 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 rather than keyword match, so a query like "what database did we pick?" surfaces a saved note reading "chose Redis for caching" even with zero keyword overlap. Embeddings are generated locally with multilingual-e5-base, 768 dimensions, so the core flow needs no external API keys.

It exposes 13 MCP tools once the server is reachable: mesh_focus, switch the active workspace, optionally prefetching recent docs, mesh_add, save a document with optional tags, auto-adding date: and source:, mesh_update, mesh_delete, and mesh_get, update, delete, and fetch a document by GUID, mesh_search, semantic search by query, optionally weighted across multiple workspaces, mesh_bytag, exact-match AND lookup across one or more tags, mesh_recent, most recently created documents, optionally filtered by type:, mesh_projects, per-project document counts via the guid: tag, mesh_tags, existing tags with counts and prefix filtering, mesh_versions, a document's similarity-linked revision chain, mesh_stats, memory statistics for the active workspace, and mesh_schema, the recognized tag prefixes and types.

Setup requires a running Mesh Memory instance, local Docker via docker compose up -d is the common path, the mcp_server.py script registered with an MCP-aware client, and MESH_API_URL pointing at the instance, default http://localhost:8000.

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

Documents are organized by workspace, one per role or project, and by a recommended tag prefix scheme, type: worklog, note, decision, research, task, rfc, status: active, completed, or archived, date: and source:, auto-added, and guid:<project-id> as a consistent project marker. Type and topic tags are inferred from nearest neighbors once a workspace has roughly 5-10 seed documents; below that, auto-tagging is skipped and documents need manual tagging until the corpus self-organizes. Cross-workspace search can weight results from related domains, for example sysadmin 0.7, security 0.2, developer 0.1, so a primary signal isn't diluted.

Documented troubleshooting covers connection failures, verify MESH_API_URL and hit /health, a 1-2 second embedding delay before a freshly saved document appears in semantic search, mesh_get confirms it exists immediately, results landing in the wrong workspace, call mesh_focus or pass workspace= explicitly, with neither, calls default to the "default" workspace, and eventually-consistent deletion, a deleted document can still surface briefly in search results. Its stated limitations: it is a knowledge store, not chat memory, so long transcripts should be summarized before saving; vector similarity isn't perfect, so mesh_bytag is preferred over mesh_search for high-precision structured lookups; embeddings run on CPU by default, and very large corpora need dedicated tuning not covered in the docs; and an optional AI categorizer needs an OpenAI-compatible LLM endpoint and is disabled by default.

Use this skill when an agent needs persistent memory across sessions, saving its own worklogs and decisions, recalling prior work by topic without remembering exact wording, sharing a long-lived knowledge base across multiple agents or teammates, organizing context by role or project via workspaces, or looking up structured tags like all type:decision entries in a project. It is not a chat-memory or conversation-transcript store, long transcripts should be summarized first, and it is not the right tool for exact structured filtering at scale without tags, since vector similarity is approximate.

Input is a document to save, content plus optional tags and workspace, or a query to search, semantic query text, tag filters, or a GUID. Output is a saved document with its auto-inferred tags, a ranked list of semantically similar documents, an exact tag-matched list, or memory and tag statistics for a workspace, served over the MCP protocol to any MCP-aware client.

PostgreSQL with the pgvector extension for storage and similarity search, the multilingual-e5-base embedding model run locally, the Model Context Protocol for client integration, Claude Code, Cursor, Claude Desktop, or any other MCP-aware agent, and an optional OpenAI-compatible LLM endpoint for AI categorization.

Individual agents or multi-agent and multi-teammate setups that need a persistent, semantic, self-hosted knowledge base spanning sessions, recalling prior decisions and worklogs by meaning rather than exact wording, without depending on an external memory API. The project is MIT licensed.