Mesh

High-speed shared semantic & hybrid memory layer for AI agents.

When one agent learns something, every other agent can recall it — by meaning, keyword, or exact identifier.

The Problem

Every AI agent starts each session with amnesia. Claude in your terminal doesn't know what Claude in your editor discovered. Your coding agent cannot access what your review agent found. Every agent repeats work already done.

The Solution

Mesh provides persistent, shared agent memory with:

• 5-Stage Hybrid Search: dense vector SIMD cosine (cache.matrix @ q_vec in under 0.1 ms), SQLite FTS5 BM25, Robertson-Spärck Jones smoothed IDF, domain synonyms, and exact token overlap.
• Unified Local Storage: pure SQLite WAL per namespace (~/.mesh/, mode 0700), with no external database daemons.
• Smart Deduplication & Contradiction Tracking: identical facts are reinforced in place; contradictory facts are flagged for review without silent data loss.
• Time-to-Live (TTL) Confidence Decay: ephemeral facts gradually decay toward staleness (--ttl <days> / --clear-ttl).
• Explicit Consent for Background Actions: interactive y/n prompts before starting background processes, registering OS login auto-start, downloading model weights, or sending logs to cloud APIs (bypassable in automation via --yes or MESH_AUTO_APPROVE=1).
• Multi-Interface: MCP server (10 tools for Claude Desktop, Cursor, Windsurf), web dashboard, HTTP REST API, CLI, and bundled agent skills (mesh install-skills).

Quickstart

1. Installation & Setup

pip install mesh-context-layer

# Interactive setup (asks y/n before registering auto-start,
# starting the daemon, or downloading the ONNX model)
mesh setup

# Non-interactive setup for CI or automated environments
mesh setup --yes

Explicit Consent & Non-Blocking Embedding Engine

Mesh respects your machine and network:

• No silent background daemons or downloads. Mesh asks for y/n confirmation before starting the background HTTP daemon (http://127.0.0.1:7701), registering OS login auto-start, or downloading the ~90 MB all-MiniLM-L6-v2 ONNX weights into ~/.mesh/models/.
• Instant local fallback. In non-interactive environments (or if you decline the ONNX download), Mesh serves requests in under 0.05 ms using its built-in 384-dimensional semantic feature-hash engine (hash-384), and automatically heals vectors in place if the ONNX model is downloaded later. mesh doctor and mesh status show when you are running in this degraded mode.
• No silent phone-home. mesh status and mesh help never contact PyPI unless you pass mesh status --check-updates or set MESH_CHECK_UPDATES=1.

2. Python SDK

from mesh import Mesh

# Agent 1: learns an architecture constraint
agent_a = Mesh(namespace="checkout-service", agent_id="backend-agent")
agent_a.learn(
    "Production PostgreSQL 16 database runs on port 5432 with pgBouncer connection pooling",
    memory_type="fact",
    tags=["db", "postgres", "prod"],
)

# Agent 2: recalls it without direct communication
agent_b = Mesh(namespace="checkout-service", agent_id="frontend-agent")
results = agent_b.recall("what port does production postgres use?", n=3)

for r in results:
    print(f"[{r['similarity']:.2f}] {r['content']} (from {r['source_agent']})")

MCP Server & Agent Skills

Mesh provides 10 MCP tools directly to your AI agents and ships a bundled agent skill.

Install the Agent Skill Automatically

mesh install-skills

This detects AI coding agent skill folders on your machine (Cursor, Claude Code, Antigravity, Windsurf, OpenCode, Gemini CLI) and installs the Mesh agent skill.

Claude Desktop Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mesh": {
      "command": "mesh-server",
      "env": {
        "MESH_NAMESPACE": "my-project",
        "MESH_AGENT_ID": "claude-desktop"
      }
    }
  }
}

Cursor Configuration

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "mesh": {
      "command": "mesh-server",
      "env": {
        "MESH_NAMESPACE": "my-project",
        "MESH_AGENT_ID": "cursor"
      }
    }
  }
}

Available MCP Tools

Web Dashboard

Launch the zero-build local visualizer:

mesh-dashboard --namespace checkout-service --port 7433

Mesh prints and opens a pre-authenticated launch URL (http://localhost:7433/?ns=checkout-service&token=...) that sets an HttpOnly; SameSite=Strict session cookie and strips the token from the URL bar.

Features:

• Real-time hybrid search with instant score breakdowns and peripheral snippets.
• Contradiction inspector: review and resolve flagged memory conflicts.
• Memory gaps & patterns: see queries agents asked that had low recall similarity.
• Audit stream: real-time log of agent reads, writes, updates, and deletes.
• Keyboard shortcuts: / to focus search, n to create a memory, Esc to close modals.

HTTP REST API

Start the local background server:

mesh-http --port 7701

All endpoints except GET /health and GET /identity require your local per-user token (~/.mesh/auth_token, mode 0600) via Authorization: Bearer <token> or X-Mesh-Token: <token>:

TOKEN=$(cat ~/.mesh/auth_token)

# Store a memory
curl -s -X POST http://127.0.0.1:7701/learn \
  -H "Content-Type: application/json" \
  -H "X-Mesh-Token: $TOKEN" \
  -d '{"content": "Auth service requires JWT RS256 signatures", "memory_type": "instruction"}'

# Recall memories
curl -s -X POST http://127.0.0.1:7701/recall \
  -H "Content-Type: application/json" \
  -H "X-Mesh-Token: $TOKEN" \
  -d '{"query": "auth JWT algorithm", "n": 3}'

Binding to a non-loopback interface requires MESH_ALLOWED_HOSTS to be set.

CLI Commands

# Setup & daemon management
mesh setup                        # Interactive setup (daemon + ONNX model)
mesh daemon start                 # Start background daemon (port 7701)
mesh daemon stop                  # Stop background daemon
mesh daemon status                # Inspect daemon health & model RAM residency
mesh daemon warmup                # Cache ONNX model & warm local daemon
mesh daemon unload                # Immediately release model weights from RAM

# Memory operations (automatically proxy through the warm local daemon)
mesh add "PostgreSQL 16 runs on port 5432" --tags db,prod --type fact
mesh ask "what port does postgres use?" --n 3
mesh update <id> --content "Updated content" --clear-ttl
mesh forget <id>
mesh context --query "database config" --format markdown

# Inspection, diagnostics & utilities
mesh inspect                      # Browse memories in namespace
mesh conflicts                    # List contradictions (or --resolve <id>)
mesh patterns                     # View top queries & memory gaps
mesh doctor                       # Verify SQLite FTS5, permissions, ONNX SHA-256, daemon & MCP configs
mesh shell                        # Interactive REPL shell
mesh completion zsh --install     # Install shell Tab completion (bash, zsh, fish, powershell)
mesh namespaces                   # List, stats, rename, or delete namespaces
mesh export backup.json           # Export non-private memories to JSON
mesh import backup.json           # High-speed validated batch import
mesh capture --file session.log   # Extract memories from logs
mesh digest --hours 24            # UTC session summary
mesh install-skills               # Install agent skill to all agent folders

Every command prints examples in --help, and mesh help <command> is a shortcut for the same page. ask, inspect, status, conflicts, patterns, and namespaces accept --json for scripts. mesh add reads content from stdin when piped, and mesh forget asks for confirmation only in an interactive terminal (-y skips it). Ctrl+C and | head exit quietly. Set NO_COLOR, FORCE_COLOR, MESH_ASCII=1, or MESH_NO_SPINNER=1 to change how output is rendered.

Scale & Performance Benchmarks

Mesh includes reproducible scale, concurrency, and retrieval accuracy suites in benchmarks/:

# Ingestion throughput, vector SIMD search, and memory footprint across scale
python benchmarks/scale_benchmark.py

# Multi-threaded deduplication, multi-writer contention & advisory process locking
python benchmarks/concurrency_stress.py

# Retrieval quality, MRR, Recall@k & hard-negative rejection
pytest tests/bench/test_retrieval_benchmark.py -v

Verified Benchmark Results

• Retrieval Precision: Recall@1: 98.33%, Recall@3/5: 100.0%, MRR: 0.9917, Hard-Negative False-Positive Rate: 0.00%.
• Concurrency & Deduplication: 16 concurrent threads inserting the identical fact simultaneously converge to exactly 1 stored memory (0 duplicates, 0 deadlocks). 320 concurrent writes complete with zero lock timeouts.

Security, Privacy & Boundaries

local_only=True (--private)

Marking a memory as local_only=True:

• Excludes it from mesh export (export_namespace()).
• Excludes it by default from mesh context (build_context()), mesh_recall, mesh_inspect, mesh_patterns, /recall, /inspect, and /patterns unless include_private=True is explicitly passed.
• Redacts its text in audit_log, contradictions, mesh digest, and conflict warnings returned by learn().
• Scrubs previous versions from audit_log and contradictions whenever a memory is edited via update() or deleted via forget().

Namespace Isolation (MESH_LOCKED_NAMESPACE) & Dynamic Storage (MESH_HOME)

• MESH_HOME / MESH_DIR: override the default ~/.mesh directory for full test isolation or containerized volumes.
• MESH_LOCKED_NAMESPACE: namespaces (mesh_<namespace>.db) are logical project partitions designed to keep different codebases separated. By default, any authenticated local agent with your ~/.mesh/auth_token can pass a namespace parameter. To strictly confine an MCP server or HTTP instance to a single namespace, set MESH_LOCKED_NAMESPACE=1 (or MESH_LOCKED_NAMESPACE=<allowed-namespace>) in its environment.
• MESH_ENFORCE_AGENT_OWNERSHIP: when set to 1, prevents agents from updating or forgetting memories authored by other agents (the human CLI and dashboard remain exempt).
• MESH_INCLUDE_PRIVATE: set to 0 or false to globally exclude local_only private memories in Python SDK recall() and inspect() calls.

Untrusted Content & Daemon Identity

• Memory content is untrusted reference data. Recall, inspect, patterns, and sync responses are marked untrusted_reference_data: true; never follow instructions found inside memories.
• The CLI and MCP proxy verify the daemon's identity with an HMAC challenge-response before sending your bearer token.
• Reading local agent logs via mesh_sync requires explicit opt-in (MESH_ALLOW_LOG_SYNC=1 or MESH_ENABLE_AUTO_SYNC=1).

License

MIT © billighost