Skip to main content
Glama
smankoo

local-memory-mcp

by smankoo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

local-memory-mcp

A local-first long-term memory system for AI coding agents, exposed as an MCP server. Built for Kiro CLI but compatible with any MCP-capable client.

Why

AI agents forget everything between sessions. This gives them persistent, searchable, semantically-aware memory — stored entirely on your machine.

Related MCP server: apex-memory

Architecture

┌─────────────────────────────────────────────────┐
│  MCP Server (stdio)                             │
│                                                 │
│  Tools: store_memory · recall · search_memories │
│         get_memory · forget · relate            │
│         query_graph · consolidate · memory_stats│
├─────────────────────────────────────────────────┤
│  Memory Engine                                  │
│  ┌───────────┬──────────┬───────────────────┐   │
│  │ Retrieval │ Embeddings│ Consolidation    │   │
│  │ (hybrid)  │ (local)   │ (decay + merge)  │   │
│  └───────────┴──────────┴───────────────────┘   │
├─────────────────────────────────────────────────┤
│  Storage Layer                                  │
│  ┌──────────┬───────────┬────────┬──────────┐   │
│  │ Memories │ Vectors   │ FTS5   │ Knowledge│   │
│  │ (SQLite) │(sqlite-vec)│(SQLite)│ Graph    │   │
│  └──────────┴───────────┴────────┴──────────┘   │
└─────────────────────────────────────────────────┘

Hybrid retrieval combines four signals into a single score:

Signal

Weight

Source

Vector similarity

50%

sqlite-vec (L2 distance on 384-dim embeddings)

Full-text search

25%

SQLite FTS5

Recency

15%

Exponential decay, 30-day half-life

Importance

10%

User-assigned + access-frequency boosting

Embeddings run fully locally via Transformers.js (ONNX runtime) using all-MiniLM-L6-v2. No API keys. No network calls after first model download.

Knowledge graph stores typed entities and weighted relations in SQLite with BFS traversal up to 3 hops.

Consolidation applies importance decay, merges near-duplicate memories, and prunes forgotten ones.

Dual-scope storage

Every memory lives in one of two scopes:

  • Global (~/.local-memory/memory.db) — your preferences, facts, cross-project knowledge

  • Project (.local-memory/memory.db in repo root) — project-specific context, decisions, patterns

The agent can query either scope or both. Project scope auto-detects from .git, package.json, Cargo.toml, pyproject.toml, or go.mod.

Tools

Tool

Description

store_memory

Store a memory with type, scope, importance, and optional entity extraction

recall

Semantic recall — hybrid search combining all four signals

search_memories

Keyword-based full-text search

get_memory

Fetch a specific memory by ID

forget

Delete a memory and cascade to embeddings + graph

relate

Create/strengthen entity relationships in the knowledge graph

query_graph

Traverse the knowledge graph from an entity (BFS, 1-3 hops)

consolidate

Decay old memories, merge duplicates, prune weak ones

memory_stats

Counts for memories, entities, and relations per scope

Quickstart

Install

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

Configure Kiro CLI

Option A — Auto-configure:

npx tsx scripts/install-kiro.ts          # global
npx tsx scripts/install-kiro.ts --project # project-level

Option B — Manual:

Add to ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/absolute/path/to/local-memory-mcp/dist/index.js"],
      "env": {
        "MEMORY_DIR": "~/.local-memory"
      }
    }
  }
}

Then restart Kiro CLI and run /mcp to verify.

Other MCP clients

Any client that speaks MCP over stdio works. The server binary is dist/index.js:

node /path/to/local-memory-mcp/dist/index.js

Environment variables

Variable

Default

Description

MEMORY_DIR

~/.local-memory

Global data directory

MEMORY_PROJECT

auto-detected CWD

Project root override

EMBEDDING_MODEL

Xenova/all-MiniLM-L6-v2

HuggingFace model for embeddings

Configuration

Tuning knobs are in src/utils/config.ts:

Parameter

Default

Description

deduplicationThreshold

0.92

Cosine similarity above which a new memory updates the existing one

consolidationThreshold

0.85

Similarity above which two memories are merged during consolidation

decayRate

0.995

Daily importance multiplier (0.995^30 ≈ 0.86, so ~14% decay/month)

minImportanceBeforePrune

0.05

Memories below this with <2 accesses get pruned

Development

npm run dev          # watch mode
npm test             # run tests (downloads model on first run, ~60s)
npm run build        # production build

Project structure

src/
├── index.ts                # Entry point — stdio transport
├── server.ts               # MCP tool definitions
├── engine/
│   ├── memory-engine.ts    # Orchestrator — store, recall, forget, consolidate
│   ├── retrieval.ts        # Hybrid scoring (vector + FTS + recency + importance)
│   ├── embeddings.ts       # Local embedding via Transformers.js
│   ├── consolidation.ts    # Decay, merge, prune lifecycle
│   └── graph.ts            # Entity relationship engine
├── storage/
│   ├── database.ts         # SQLite + sqlite-vec + FTS5 initialization
│   ├── schema.ts           # Drizzle ORM schema
│   ├── memory-store.ts     # CRUD for memories table
│   ├── vector-store.ts     # sqlite-vec operations
│   ├── fts-store.ts        # FTS5 search with query sanitization
│   └── graph-store.ts      # Entity + relation tables, BFS traversal
└── utils/
    ├── config.ts           # Environment + defaults
    ├── scoring.ts          # Recency decay, hybrid scoring, cosine similarity
    └── id.ts               # nanoid generation

Tech stack

  • TypeScript + tsup (ESM, Node 22)

  • better-sqlite3 + Drizzle ORM for structured storage

  • sqlite-vec for vector similarity search

  • SQLite FTS5 for full-text search

  • @huggingface/transformers for local embeddings (ONNX)

  • @modelcontextprotocol/sdk for the MCP server

  • Vitest for testing

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors

Related MCP Servers

  • apex-memory

    JJerryChoi
    A
    license
    Not graded
    quality
    C
    maintenance
    Persistent memory for AI coding agents. Enables agents to save and recall decisions, patterns, bugs, and context across sessions via an MCP server with local SQLite storage.
    4 npm
    2
    MIT

  • aimem

    yogesh-joshi-0333
    A
    license
    Not graded
    quality
    B
    maintenance
    A local-first MCP server that gives AI coding assistants persistent, project-scoped memory across sessions, storing facts and decisions in a SQLite database under .aimem/ and exposing tools for searching, storing, and conflict-resolving memories.
    203 npm
    MIT