Local Memory MCP Server

A local-first MCP server that gives AI agents shared, durable memory through hybrid semantic search, SQLite FTS5, and a knowledge graph—without Docker or a required cloud service.

Why use it?

• Shared across agents: one SQLite database can serve Codex, Claude, desktop clients, IDE integrations, and custom MCP clients.
• Hybrid recall: when sqlite-vec is available, local all-MiniLM-L6-v2 embeddings and FTS5 keyword evidence are merged. FTS remains available as the explicit fallback.
• Temporal recall: search natural-language periods such as last week or in 2025, or pass an explicit ISO startDate and endDate.
• Adaptive ranking: relevance, time-decayed importance, tags, and bounded recent familiarity work together without rewriting importance on every recall.
• Auditable lifecycle: memories can be reinforced, marked outdated or incorrect, restored, exported, or forgotten.
• Structured context: entities, relations, observations, conversations, tasks, and todos live beside free-form memories.
• Local by default: memory data stays in your configured SQLite file. Optional LLM features send input only to the OLLAMA_URL you configure.

For every option and tool, see the extended guide.

Requirements

• Node.js 22 or newer on a supported LTS release.
• Python and C++ build tools when better-sqlite3 has no matching prebuild.
• Windows users can install Desktop development with C++ through Visual Studio Build Tools.

Windows ARM64 semantic search is supported by a bundled, checksum-verified sqlite-vec v0.1.9 DLL. WSL2 remains a supported alternative.

Quick start

Add the published package to an MCP client:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@beledarian/mcp-local-memory@2"],
      "env": {
        "ARCHIVIST_STRATEGY": "nlp"
      }
    }
  }
}

The default database is ~/.memory/memory.db. The first semantic recall may download the local embedding model.

Global installation provides both memory and mcp-local-memory:

npm install -g @beledarian/mcp-local-memory@2
memory --help

From source:

git clone https://github.com/Beledarian/mcp-local-memory.git
cd mcp-local-memory
npm install
npm run build
npm start

See the Codex + WSL2 setup when the database or server runs inside Linux.

Remote Server & Docker Deployment (SSE)

mcp-local-memory supports native HTTP/SSE transport for centralized setups across multiple workstations, laptops, Tailnets, or VPS instances:

# Run standalone SSE server on port 8320 with optional Bearer token auth:
node dist/index.js --transport sse --port 8320 --token "your-secret-token"

# Or run via Docker Compose:
docker compose up -d

Configure your remote MCP client (mcp_config.json):

{
  "mcpServers": {
    "memory": {
      "url": "https://your-server.ts.net:8320/sse",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

Essential configuration

All scoring, context, archivist, task, and extension variables are documented in the configuration reference.

How recall works

recall supports both topical and temporal questions:

• Semantic vector and FTS5 keyword candidates are retrieved independently and merged, so an exact term is not hidden by a semantic result.
• Natural-language dates such as yesterday, last week, and in 2025 are recognized in the query. ISO startDate and endDate filters are also available.
• Weak matches are omitted, near-duplicates are collapsed, and outdated or incorrect memories stay hidden unless explicitly requested.
• Relevant results are ranked using retrieval evidence, query coverage, tags, time-decayed importance, and a small recent-familiarity signal.
• Each returned active memory can record one familiarity exposure per normalized-query hash and UTC day. The contribution is temporary and bounded to 0.03 by default; it does not rewrite importance or refresh decay.

reinforce_memory provides the stronger, durable feedback path:

• used or important record positive evidence.
• irrelevant lowers importance.
• incorrect or outdated suppresses the memory without deleting history.
• restore returns a suppressed memory to active recall.

The extended scoring guide documents the formula, thresholds, deduplication, privacy limits, decay, and every familiarity control.

Entities, relations, and the graph

Free-form memories and structured knowledge complement each other:

• Entities represent people, projects, places, topics, or other named concepts. Each has a type, importance, and appendable observations.
• Relations are directional triples such as Project A --[uses]--> SQLite. Creating a relation also creates any missing endpoint as an Unknown entity.
• Automatic extraction can identify entities and relations while saving a fact. Use ARCHIVIST_STRATEGY=nlp for local extraction, llm for the configured Ollama endpoint, or passive for manual graph maintenance.
• Graph exploration can return an overview or a centered one- or two-hop neighborhood with entity observations, relations, and related memories.
• Graph maintenance supports renaming or deleting entities, removing exact observations, and deleting individual relations. Entity renames update connected relations.
• Clustering groups semantically related memories and entities into topic overviews when embeddings are available.

Use recall for ranked free-form retrieval and read_graph when connections between named concepts matter. They are complementary views of the same local knowledge base.

MCP surface

See the complete tool reference for arguments and lifecycle behavior.

Upgrading safely

When upgrading from 1.x:

• move to Node.js 22;
• back up MEMORY_DB_PATH;
• expect automatic additive schema migration;
• note that MEMORY_SEMANTIC_WEIGHT now means relevance versus importance;
• recall no longer raises importance or refreshes decay;
• run importance normalization only if you want to reset historical passive popularity.

The project does not claim crash-proof, zero-loss migration under every interruption scenario, so a verified backup remains the safety boundary.

Older releases passively increased importance and access_count during recall. Preview normalization before changing anything:

npm run normalize:importance -- --db ~/.memory/memory.db

Applying normalization is optional and requires an explicit, non-existing backup path. See the migration and normalization guide.

Documentation

• Extended installation, configuration, and operations
• Short agent instructions
• Comprehensive agent prompt
• Changelog
• Test and smoke-probe guide
• Windows ARM64 sqlite-vec provenance

Development

These commands require a source checkout:

npm install
npm run build
npm test

npm test covers scoring, schema migration, lifecycle and familiarity, privacy/provenance, MCP contracts, packaging, and native vector or FTS fallback.

License

MIT