convez.ai
MCP ServerAutomaçãoIntermediário
MK-986123

Server Memory

MK-986123/server-memory

Memória local durável para agentes MCP com SQLite e FTS5

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server local-first para memória durável de agentes, com armazenamento em SQLite e busca por FTS5. Implementa um grafo de conhecimento com entidades, observações, relações, tags e histórico de atividades, mantendo dados privados e locais.

Instalação

$npx convez-ai MK-986123/server-memory

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
0
Saúde
71%
Último commit
há 1 mês
Versão
—
Issues abertas
7
Contribuidores
1

Casos de uso

  • Agentes Claude com memória persistente de conversas e contexto
  • Sistemas que precisam recuperar informações rapidamente com busca semântica
  • Aplicações que requerem privacidade total dos dados de memória

Veredito

Solução robusta e bem arquitetada para persistência de memória em agentes MCP. Abordagem local-first com SQLite é segura, mas requer conhecimento técnico para integração; ideal para aplicações que priorizam privacidade e controle total dos dados.

README

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


Overview

server-memory is a local-first Model Context Protocol (MCP) server for durable agent memory: entities, observations, relations, tags, activity, and fast recall backed by SQLite and FTS5.

It is intentionally boring where memory should be boring.

Data stays in local databases unless you export it. The default MCP transport is stdio, and the optional shared HTTP daemon is bound to localhost by default.

At a glance

CapabilityImplementation
StorageSQLite with WAL mode and FTS5 search
Memory modelEntities, observations, relations, tags, and activity
MCP interface20 tools; no resources or prompts
Default transportstdio
Shared modeLocalhost HTTP daemon with a stdio proxy
Memory scopesWorkspace memory and optional global preference memory
RetrievalFTS5 search with optional embedding assistance
Data pathsPlatform-native user data and runtime directories through platformdirs

Highlights

  • Local knowledge graph: Stores entities, observations, relations, tags, and activity in SQLite with WAL mode and FTS5 search.
  • MCP tools: Exposes 20 tools for graph writes, recall, timeline queries, import/export, tagging, backup, and statistics.
  • Compact context: Provides token-budgeted memory_context output for routine agent recall.
  • Optional embeddings: Supports embedding-assisted retrieval through the embeddings extra.
  • Memory scopes: Keeps workspace memory and global preference memory separate by default.
  • Shared mode: Provides a localhost HTTP daemon and stdio proxy for clients that need one shared process.
  • Platform-native paths: Uses platformdirs for per-user data and runtime directories.

Architecture

Default stdio mode

┌────────────┐         stdio         ┌─────────────────────┐
│ MCP client │ ────────────────────> │    server-memory    │
└────────────┘                       │    FastMCP server   │
                                     ├─────────────────────┤
                                     │ Workspace SQLite DB │
                                     │                     │
                                     │ Global preferences  │
                                     │ DB, when enabled    │
                                     └─────────────────────┘

Optional shared mode

┌────────────┐      stdio       ┌─────────────────────┐
│ MCP client │ ───────────────> │ server-memory-proxy │
└────────────┘                  └──────────┬──────────┘
                                         │
                                         │ HTTP
                                         │ 127.0.0.1:8765/mcp
                                         ▼
                              ┌─────────────────────┐
                              │ server-memory-serve │
                              │ FastMCP daemon      │
                              └─────────────────────┘

Requirements

  • Python 3.10 or newer
  • SQLite with FTS5 enabled
  • macOS, Ubuntu, or Windows for the GitHub Actions support matrix

The CI workflow is configured to test:

  • Python 3.10 through 3.14 on Ubuntu
  • Python 3.10 and 3.14 on ubuntu-latest
  • Python 3.10 and 3.14 on windows-latest
  • Python 3.10 and 3.14 on macos-latest

Installation

Core installation

Install directly from this GitHub repository:

python -m pip install "server-memory @ git+https://github.com/MK-986123/server-memory.git"

Installation with embeddings

python -m pip install "server-memory[embeddings] @ git+https://github.com/MK-986123/server-memory.git"

Development checkout

git clone https://github.com/MK-986123/server-memory.git
cd server-memory

python -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

On Windows PowerShell:

.venv\Scripts\Activate.ps1

Install development and embedding dependencies together:

python -m pip install -e ".[dev,embeddings]"

Quick start

Run the stdio server

server-memory

Equivalent module form:

python -m server_memory

Use a dedicated project database

MEMORY_DB_PATH=<PROJECT_ROOT>/memory.db server-memory

Use the equivalent environment-variable syntax for your shell when running on Windows.

Run the shared localhost daemon

server-memory-serve \
  --host 127.0.0.1 \
  --port 8765 \
  --transport streamable-http

Connect a stdio-only client to the daemon

server-memory-proxy --url http://127.0.0.1:8765/mcp

MCP client configuration

Direct stdio server

{
  "mcpServers": {
    "server-memory": {
      "command": "server-memory",
      "env": {
        "MEMORY_PROJECT": "<PROJECT_NAME>"
      }
    }
  }
}

Shared daemon proxy

Start server-memory-serve separately, then configure the MCP client to launch the proxy:

{
  "mcpServers": {
    "server-memory": {
      "command": "server-memory-proxy",
      "args": [
        "--url",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Tool reference

server-memory registers MCP tools only. It does not register resources or prompts.

Scope behavior

Most tools accept one of three scopes:

ScopeBehavior
workspaceOperates on the current workspace database and remains the default for ordinary project memory
globalOperates on the global preferences database
allCombines supported workspace and global results with source labels

Preference-tagged writes still auto-route to the global database when global preference routing is enabled.

[!IMPORTANT] Destructive operations require an explicit workspace or global scope. They reject scope="all" to prevent accidental cross-database deletion, merging, or tag removal.

ToolPurposeMain inputs
memory_contextCompact scoped recall for ordinary agent contexthint, project, limit, scope
memory_context_fullLarger bootstrap context with pinned and recent itemsproject, budget, scope
create_entitiesAdd entities and optional initial observationsentities, scope
add_observationsAdd observations to existing entitiesobservations, scope
create_relationsConnect existing entitiesrelations, scope
read_graphRead graph data, compressed by defaulttags, entity_types, limit, include_deleted, compress, scope
search_nodesFTS5 search with filtersquery, tags, entity_types, time_range, limit, compress, scope
open_nodesOpen named entities and optional neighborsnames, depth, scope
log_activityRecord a development or session eventaction, summary, entity_names, tags, metadata, scope
query_timelineQuery activity historytime_range, start, end, actions, entity_name, session_id, limit, scope
manage_tagsList, create, delete, apply, remove, or clean tagsaction, name, entity_name, tag_name, scope
merge_entitiesMerge one entity into anothersource, target, strategy, scope
export_graphExport graph as JSON or JSONLformat, scope
import_graphImport JSON or JSONL graph datadata, scope
memory_statsReturn counts and storage statisticsscope
backup_memoryCopy a SQLite databasedest_path, scope
get_observation_historyShow observation versions for an entityentity_name, content_prefix, scope
delete_entitiesSoft-delete or hard-delete entitiesentityNames, hard, scope
delete_observationsDelete selected observationsdeletions, scope
delete_relationsDelete selected relationsrelations, scope

Write tools modify the selected SQLite database. backup_memory writes a database backup. export_graph can print sensitive memory content, so review exports before sharing them.


Configuration

Configuration is environment-driven. Empty path overrides in .env.example use the platform defaults.

Storage and scope

VariableDefaultMeaning
MEMORY_DB_PATHPlatform user data directory, workspace-namespaced when a project root is detectedWorkspace SQLite database
MEMORY_PROJECTEmptyDefault project scope
MEMORY_GLOBAL_DB_ENABLEDtrueEnable the global preferences database
MEMORY_GLOBAL_DB_PATHPlatform user data directoryGlobal preferences SQLite database
MEMORY_GLOBAL_PREFERENCE_ROUTING_ENABLEDtrueRoute preference-tagged writes to global memory
MEMORY_WORKSPACE_ROOTUnsetExplicit workspace root for default database placement
MEMORY_WORKSPACE_IDUnsetExplicit workspace identifier for default database placement

Retrieval and compression

VariableDefaultMeaning
MEMORY_COMPRESSION_LEVEL4Compression level from 0 through 4
MEMORY_TOKEN_BUDGET2000Output token budget
MEMORY_EMBEDDING_MODELall-MiniLM-L6-v2Optional embedding model
MEMORY_EMBEDDING_ENABLEDtrueEnable embedding search and backfill
MEMORY_WRITE_EMBEDDING_BUDGET_MS10000Write-path embedding budget
MEMORY_DEDUP_THRESHOLD0.92Semantic deduplication threshold

Runtime and shared daemon

VariableDefaultMeaning
MEMORY_IMPORT_JSONLUnsetImport JSONL on startup
MEMORY_SESSION_IDUnsetSession identifier for activity logging
MEMORY_HTTP_AUTH_ENABLEDtrueRequire bearer authentication for the shared HTTP daemon
MEMORY_AUTH_TOKEN_PATHPlatform runtime directoryLocal HTTP daemon token file

Development

Install the development dependencies:

python -m pip install -e ".[dev]"

Run the local validation sequence:

python -m compileall -q src tests scripts
python -m ruff check .
python -m pytest -q
python -m build
python -m twine check dist/*
python scripts/inspect_wheel.py dist
python -m pip_audit

Verify the installed entry points:

python scripts/smoke_stdio.py server-memory
server-memory-serve --help
server-memory-proxy --help

The stdio smoke test sends an MCP initialize request to the installed entry point and fails if stdout contains non-protocol output.

See CONTRIBUTING.md for contribution guidance.


Security and privacy

[!IMPORTANT] Memory databases, exports, backups, and activity logs can contain sensitive user data.

  • The stdio server writes protocol data to stdout. Diagnostics should go to stderr or logs.
  • The shared HTTP daemon defaults to 127.0.0.1 and local bearer-token authentication.
  • The bearer token is generated locally and stored under a platform-native runtime directory unless MEMORY_AUTH_TOKEN_PATH is set.
  • No external service credentials are required for the core server.
  • Optional embeddings may load local or cached model files depending on the environment and installed extras.
  • Review exported graph content before sharing it.
  • Do not commit live memory databases, token files, or backups.

Report vulnerabilities through GitHub private vulnerability reporting when available. Do not include secrets or private memory exports in public issues.

See SECURITY.md for the project security policy.


CI and supply chain

GitHub Actions are configured to run:

  • syntax validation
  • Ruff linting
  • pytest across the supported Python and operating-system matrix
  • wheel and source distribution builds
  • wheel-content inspection
  • clean installed-package checks outside the repository checkout
  • MCP stdio and installed-command smoke tests
  • pip-audit
  • CodeQL
  • Dependency Review

Dependabot is configured for Python dependencies and GitHub Actions.

The workflow uses GitHub-hosted ubuntu-latest, windows-latest, and macos-latest labels. These labels refer to GitHub's latest stable runner images and can temporarily lag the newest vendor operating-system release during image migrations.


Troubleshooting

SymptomCheck
no such module: fts5Use a Python build linked against SQLite with FTS5 enabled.
MCP client hangs at startupRun python scripts/smoke_stdio.py server-memory and inspect stderr.
Multiple clients lock the databaseRun one server-memory-serve process and connect clients through server-memory-proxy.
Proxy returns an authentication failureRestart the daemon and client so both read the same MEMORY_AUTH_TOKEN_PATH.
Memory is stored in an unexpected locationSet MEMORY_DB_PATH, MEMORY_WORKSPACE_ROOT, or MEMORY_WORKSPACE_ID explicitly.

License

[!CAUTION] No open-source license has been selected. Public visibility does not grant permission to copy, modify, redistribute, or reuse the project.

Ver o original no GitHub

Bom para

Relacionados