convez.ai
MCP Server
3036344737-Dai-Hongxi

Semi-Pervault-MCP

3036344737-Dai-Hongxi/Semi-Pervault-MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Local-first long-term memory MCP server for AI agents, backed by SQLite, hybrid retrieval, persona extraction, and graph context.

Instalação

$npx convez-ai 3036344737-Dai-Hongxi/Semi-Pervault-MCP

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
1
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

Semi-Pervault MCP is a local 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 that memory 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.

Why It Exists

Most AI tools are brilliant in the moment and forgetful by design. Semi-Pervault MCP gives them a durable, inspectable memory surface:

NeedWhat Semi-Pervault Provides
Remember me across sessionsLong-term local storage for facts, preferences, decisions, and progress
Recall the right contextHybrid retrieval across facts, full text, embeddings, and graph context
Keep memory explainableEvidence trails, admission scores, and revision audit history
Stay private by defaultSQLite on your machine, with a loopback-only daemon
Avoid MCP process fragilityA thin MCP bridge forwards to a resident daemon that owns background work

What It Does

  • Stores long-term memory for facts, preferences, decisions, events, relationships, and project state.
  • Retrieves with hybrid search across structured facts, full-text search, embeddings, and graph context.
  • Builds stable persona context from repeated preferences and high-confidence traits.
  • Extracts knowledge graph links between people, projects, topics, and events.
  • Generates reflections through a background consolidation loop.
  • Explains beliefs with supporting memories, confidence, admission scores, and audit trail.
  • Keeps data local-first with SQLite storage and a loopback daemon.

Why Semi-Pervault

Semi-Pervault is not just a stdio process with a memory table behind it. It is a local memory daemon exposed through MCP.

Common memory MCP patternSemi-Pervault's difference
The MCP server process owns everythingMCP is only the plug. A resident daemon owns storage, background jobs, and retrieval.
Flat notes, JSON, or vector-only recallFour memory layers: raw memories, structured facts, stable persona, and higher-level reflections.
Retrieval returns matching snippetsHybrid recall combines facts, FTS, vector search, graph context, persona, and reflections.
Memories are hard to auditmemory_why returns evidence, confidence, admission scores, and revision history.
Background work stops when the client closesThe daemon keeps enrichment, consolidation, decay, and sleep-agent work alive.
Privacy depends on external servicesSQLite stays on your machine; providers are optional and used for enrichment only.

The short version: Semi-Pervault is built for agents that need memory to become durable, structured, explainable, and private, not just searchable.

Use Cases

Semi-Pervault MCP is most useful when your AI assistant needs continuity:

Use caseExample memory
Personal assistant context"I prefer concise technical explanations with concrete next steps."
Project continuity"Semi-Pervault MCP uses a thin MCP bridge and a resident FastAPI daemon."
Research and study notes"I am studying data science and engineering at HKU."
Decision tracking"We chose SQLite-first storage to keep memory local and inspectable."
Relationship and collaboration context"Alice owns backend reliability decisions for Project X."

Try asking your MCP client:

Remember that I am building a local-first memory MCP server called Semi-Pervault.

Then later:

What do you remember about my memory MCP project, and why?

The second question can use memory_search, persona_get, or memory_why depending on the context.

Architecture

The architecture is simpler than it looks:

MCP is the connector. The daemon is the memory engine. SQLite is the local source of truth.

Semi-Pervault is split into three boundaries:

AreaRole
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.

1. Runtime boundary

This is the part users need to understand first. Claude, Codex, Cursor, OpenClaw, Hermes, and other clients do not talk to SQLite. They talk to MCP. MCP forwards to the daemon. The daemon is the only writer.

flowchart LR
  Client["AI client or local runtime<br/>Claude / Codex / Cursor<br/>OpenClaw / Hermes"] -->|"MCP stdio"| Bridge["MCP host<br/>apps/mcp_host/server.py<br/>thin bridge"]
  Bridge -->|"127.0.0.1 /core/*<br/>X-Pervault-Token"| Daemon["Memory daemon<br/>backend/main.py<br/>only DB writer"]
  UI["Optional local UI<br/>or future browser adapter"] -->|"HTTP"| Daemon
  Daemon -->|"read / write"| DB["SQLite<br/>~/.pervault/data.db"]
  Daemon -->|"starts once"| Runtime["MemoryRuntime<br/>jobs + consolidation<br/>decay + sleep agent"]
  Runtime --> DB
  Daemon -.-> Providers["Optional LLM / embedding APIs<br/>enrichment only"]

2. Memory engine

Inside the daemon, memory is not stored as one flat blob. New memories land as raw events, then background jobs enrich them into facts, graph edges, persona traits, and reflections.

flowchart TB
  Store["memory_store / memory_update"] --> Raw["Layer 1<br/>memory_items<br/>raw episodic memory"]
  Store --> Jobs["background_jobs<br/>persistent enrichment queue"]

  Jobs --> Admission["Admission + importance<br/>should this matter later?"]
  Jobs --> Facts["Layer 2<br/>structured_facts<br/>durable facts"]
  Jobs --> Graph["Graph memory<br/>graph_nodes + graph_edges"]
  Jobs --> Persona["Layer 3<br/>user_persona<br/>stable traits"]
  Jobs --> Reflection["Layer 4<br/>memory_reflection<br/>higher-level insights"]
  Jobs --> Index["Retrieval indexes<br/>memory_fts + vec_items"]

  Query["memory_search / persona_get<br/>memory_graph / memory_why"] --> Retrieval["Hybrid retrieval<br/>intent routing + ranking + provenance"]
  Retrieval --> Raw
  Retrieval --> Facts
  Retrieval --> Graph
  Retrieval --> Persona
  Retrieval --> Reflection
  Retrieval --> Index

Design invariants

InvariantWhy it matters
One writerThe daemon is the only process that writes to SQLite, so MCP client restarts cannot corrupt background work.
Thin MCP bridgeapps/mcp_host/server.py only reads ~/.pervault/core_token and forwards tool calls to 127.0.0.1:8000/core/*.
Persistent background queueEnrichment jobs live in SQLite, so graph/persona/reflection work is not tied to a short-lived MCP process.
Explainable memoryImportant beliefs can be traced back through source memories, admission scores, confidence, and revision logs.
Provider-optional local coreBasic storage and non-vector recall work locally; LLM and embedding keys improve enrichment and retrieval quality.

Data model

LayerSQLite tablesPurpose
Layer 1: episodic memorymemory_itemsRaw memories, source tags, weights, admission scores, revision state.
Layer 2: structured factsstructured_factsNormalized facts extracted from durable memories.
Layer 3: personauser_personaStable user traits backed by source memory evidence.
Layer 4: reflectionsmemory_reflectionHigher-level insights generated by the sleep agent.
Graph contextgraph_nodes, graph_edgesEntity and relationship memory for people, projects, topics, and events.
Retrieval indexesmemory_fts, vec_itemsFull-text and vector search surfaces for hybrid recall.
Evidence and auditmemory_admission_log, preference_revision_logAdmission evidence, confidence history, and correction trail.
Async orchestrationbackground_jobs, scheduler logsPersistent queue and run history for enrichment, consolidation, and sleep-agent work.

The write path is intentionally boring: tools and UI call the daemon, the daemon calls memory_core, and memory_core persists to local SQLite. That separation keeps the MCP process replaceable while the memory engine stays alive.

MCP Tools

ToolPurpose
memory_storeStore a long-term memory item.
memory_searchRetrieve relevant memories with hybrid search.
memory_graphQuery graph context for a topic.
memory_updateRevise an existing memory.
persona_getRead stable user persona traits.
reflections_listRead higher-level reflections generated by the background agent.
memory_whyExplain a belief with supporting memories, scores, and audit trail.
memory_statsShow memory counts and admission statistics.

Quick Start

Important: model/API setup

Semi-Pervault MCP is a memory layer, not a model provider. You still need an AI client or runtime that can call MCP tools.

There are two separate API layers:

LayerWhat you need
AI client / model runtimeClaude Desktop, Codex, and similar cloud-model clients must be configured with their own account or API access before they can use this MCP server. OpenClaw / Hermes-style local runtimes do not need a cloud API for the client side if the local model is already installed and running.
Semi-Pervault enrichmentOPENAI_API_KEY and embedding keys are optional for basic storage, but needed for LLM enrichment, embeddings, stronger hybrid retrieval, and some background intelligence. Without them, the daemon still stores memories and falls back to non-vector retrieval paths.

If the MCP client cannot call a model yet, Semi-Pervault will not fix that part. Start your client/runtime first, then connect this memory server.

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"
      ]
    }
  }
}

Find your uv path with:

which uv

Restart your MCP client after editing its config.

Bridge-specific details live in apps/mcp_host/README.md.

Configuration

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

For a first local test, you can leave provider keys empty and use the basic memory path. Add LLM and embedding keys when you want enrichment, vector retrieval, persona extraction, graph extraction, and stronger reflections.

VariableDescription
OPENAI_API_KEY, OPENAI_BASE_URL, LLM_MODELLLM settings used by enrichment and routing.
GEMINI_API_KEY, EMBEDDING_MODEL, EMBEDDING_BASE_URL, EMBEDDING_DIMEmbedding settings for vector retrieval.
PERVAULT_DB_PATHSQLite database location. Defaults to ~/.pervault/data.db in daemon usage.
AUTH_PASSWORD, API_KEY, SESSION_SECRETBackend auth/session settings for HTTP routes.
CONSOLIDATION_SCHEDULER_ENABLED, WEIGHT_DECAY_SCHEDULER_ENABLED, SLEEP_AGENT_ENABLEDBackground maintenance toggles.

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

Project Map

.
├── apps/mcp_host/          # MCP stdio bridge
├── backend/                # FastAPI daemon and HTTP routes
├── packages/memory_core/   # Framework-free memory kernel
├── docs/                   # Architecture and planning notes
├── RUN.command             # macOS helper to start the daemon
└── README.md

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:

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados