Semi-Pervault MCP

Local-first long-term memory for AI agents. Semi-Pervault MCP gives Claude Desktop, Cursor, and other MCP clients a private memory layer that lives on your machine.

Semi-Pervault MCP is a local-first memory server built around Pervault's four-layer memory architecture. It stores important facts, preferences, decisions, project context, and relationship notes in a local SQLite database, then exposes them as MCP tools for agentic workflows.

The goal is simple: let your AI tools remember useful context across sessions without sending your private memory store to a hosted service.

What It Does

• Long-term memory storage for facts, preferences, decisions, events, and project progress.
• Hybrid retrieval across structured facts, full-text search, embeddings, and graph context.
• Persona extraction for stable user traits, preferences, and recurring patterns.
• Knowledge graph context for people, projects, topics, and relationships.
• Reflection generation through a background sleep-agent style consolidation loop.
• Evidence tracing so the system can explain why it believes something.
• Local-first privacy with SQLite storage on your own machine.

Architecture

This repository is the MCP product slice of the larger Pervault memory system. It is split into three boundaries:

| Area | Role | |---|---| | apps/mcp_host/ | Thin MCP bridge. It exposes tools over stdio and forwards calls to the local daemon. | | backend/ | Resident FastAPI daemon. It owns HTTP APIs, auth, background jobs, and all writes to data.db. | | packages/memory_core/ | Framework-free memory kernel: schema, models, write pipeline, retrieval, graph, persona, reflections, and consolidation. |

Runtime flow:

MCP client
  -> apps/mcp_host/server.py
  -> http://127.0.0.1:8000 + X-Pervault-Token
  -> backend daemon
  -> memory_core
  -> local SQLite

The MCP host intentionally does not open the database or run background loops. The backend daemon is the only writer of the local memory database.

MCP Tools

| Tool | Purpose | |---|---| | memory_store | Store a long-term memory item. | | memory_search | Retrieve relevant memories with hybrid search. | | memory_graph | Query graph context for a topic. | | memory_update | Revise an existing memory. | | persona_get | Read stable user persona traits. | | reflections_list | Read higher-level reflections generated by the background agent. | | memory_why | Explain a belief with supporting memories, scores, and audit trail. | | memory_stats | Show memory counts and admission statistics. |

Quick Start

Requirements

• Python 3.11+
• uv

1. Start the local daemon

From the project root, double-click RUN.command, or run:

cd backend
cp .env.example .env
uv run python -m uvicorn main:app --host 127.0.0.1 --port 8000

The daemon binds to 127.0.0.1 only. On first use it creates a local pairing token at:

~/.pervault/core_token

The default database path is:

~/.pervault/data.db

Set PERVAULT_DB_PATH if you want to store the database somewhere else.

2. Connect an MCP client

Claude Desktop example:

{
  "mcpServers": {
    "pervault-memory": {
      "command": "<absolute path to uv>",
      "args": [
        "--directory",
        "<absolute project path>/apps/mcp_host",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

You can find the uv path with:

which uv

Restart your MCP client after editing its config. See apps/mcp_host/README.md for bridge-specific details.

Configuration

The backend config template is backend/.env.example.

Common settings:

| Variable | Description | |---|---| | OPENAI_API_KEY, OPENAI_BASE_URL, LLM_MODEL | LLM settings used by enrichment and routing. | | GEMINI_API_KEY, EMBEDDING_MODEL, EMBEDDING_BASE_URL, EMBEDDING_DIM | Embedding settings for vector retrieval. | | PERVAULT_DB_PATH | SQLite database location. Defaults to ~/.pervault/data.db in daemon usage. | | AUTH_PASSWORD, API_KEY, SESSION_SECRET | Backend auth/session settings for HTTP routes. | | CONSOLIDATION_SCHEDULER_ENABLED, WEIGHT_DECAY_SCHEDULER_ENABLED, SLEEP_AGENT_ENABLED | Background maintenance toggles. |

If embedding credentials are not configured, retrieval falls back to non-vector search paths.

Development

Run checks from each package directory:

# memory kernel
cd packages/memory_core
env PYTHONPYCACHEPREFIX=/tmp/pervault-pycache uv run python -m pytest tests/ -q

# backend daemon
cd backend
env PYTHONPYCACHEPREFIX=/tmp/pervault-pycache uv run python -m pytest tests/ -q

# MCP bridge
cd apps/mcp_host
uv run python -m pytest -q --ignore=tests/e2e_roundtrip.py

Design Notes

• The daemon is local-first and SQLite-first.
• The MCP bridge is deliberately thin and stateless.
• memory_core is framework-free and guarded against web-framework imports.
• Long-running side effects are handled by the daemon, not the MCP stdio process.
• Data is private by default, but external LLM or embedding providers may receive text you send to them through configured API keys.

Further reading:

• docs/derivative/01-架构改造方案.md
• docs/plan/four-memory-architecture-integration-plan.md
• packages/memory_core/README.md

License

MIT. See LICENSE.