Skip to main content
Glama

LocalMCP

One local memory store for your coding agents. Save a decision in Claude Code, retrieve it in Codex, and carry useful context into the next session.

LocalMCP is a self-hosted Model Context Protocol server backed by PostgreSQL, pgvector and Ollama. Each client starts a small stdio process; all processes use the same database. There is no hosted account or embedding API key.

Русский README · Client setup · Architecture · Credentials · Contributing

This shares saved knowledge. A second session sees a new memory when it next calls a tool. The MCP host decides when to call memory tools; full chat transcripts and hidden agent context are not synchronized.

Capabilities

Checked items describe the implementation. Verify your client connection and operating system after setup.

  • Share one persistent store across multiple MCP clients and sessions.

  • Save facts, decisions, incidents, preferences, references and snippets.

  • Search by meaning and words, with project, kind and tag filters.

  • Return short search excerpts and retrieve complete memories separately.

  • Update, supersede with history retained, and delete memories.

  • Detect near-duplicate writes when embeddings are available.

  • Import Markdown incrementally from configured directories, with a change preview.

  • Continue lexical search while Ollama is unavailable and fill missing vectors after recovery.

  • Provide optional prompt-time recall for Claude Code through manually configured hooks.

  • Diagnose database connectivity and embedding availability.

  • Prepare and publish user-approved bug reports, feature requests and help requests to the project's GitHub Issues.

Related MCP server: Sugar

Technical requirements

Component

Requirement

OS

macOS, Linux or Windows; see the compatibility status below

Runtime

Node.js 22+ and npm; Git to clone the repository

Database

Running Docker with Compose and Linux-container support; the project supplies PostgreSQL + pgvector configuration

Embeddings

Running Ollama with bge-m3 downloaded (1024 dimensions)

Client

Codex or Claude Code supporting local stdio MCP servers

Local ports

5446 for PostgreSQL, 11434 for Ollama; 5447 for integration tests only

Internet

Required to download code, packages, the database image and model; GitHub connectivity is needed to submit issues

Issue submission — optional

GitHub CLI (gh), the user's GitHub login and permission to create issues in the project repository

Minimum RAM, CPU and disk space have not been measured; budget for Docker, the embedding model and your corpus. Normal storage and embedding operations use the configured local services; your agent provider has its own connectivity requirements.

Install with Codex or Claude Code

Give your agent this request:

Install LocalMCP from https://github.com/al-mighty/localmcp. Read the README and the instructions for my OS. Check Node.js 22+, Git, Docker Compose and Ollama; tell me if anything is missing. Clone the project, create the configuration, install dependencies, build the service, pull bge-m3, start the database and run diagnostics. Register the MCP server with the client I am using, preserving existing settings. After reconnecting, verify saving and finding a memory under project demo. Suggest memory-use instructions for my working projects; configure note import and hooks according to my preferences.

The agent needs permission to access files, run commands, use the network and reach Docker. OS prompts and client reconnection may require your participation. LocalMCP itself needs no external API keys. See client setup for registration details and a cross-client sharing example.

Manual setup

Prerequisites: Node.js 22+, npm, Docker with Compose, and Ollama running locally. The default embedding model is bge-m3 (1024 dimensions).

git clone https://github.com/al-mighty/localmcp.git
cd localmcp
npm run setup          # creates local config, random DB password; preserves existing files
npm ci
npm run build
ollama pull bge-m3
npm run db:up          # PostgreSQL on 127.0.0.1:5446; waits for readiness
npm run migrate
npm run doctor

If Ollama is not already running, start it using the Ollama app or ollama serve in another terminal. The database volume persists across container restarts. docker compose down -v deletes it; use npm run db:down to stop without deleting data.

Connect both clients

Run from this checkout after building:

claude mcp add --scope user localmcp -- node "$PWD/dist/index.js"
codex mcp add localmcp -- node "$PWD/dist/index.js"

Restart or reconnect your clients. Ask one to save a decision under project demo, then ask the other to find that decision under the same project. memory_stats verifies connectivity.

See client setup for explicit configurations, suggested agent instructions and optional Claude Code hooks. Client registration changes your local configuration; LocalMCP does not install hooks or modify agent settings automatically.

Memory tools

Tool

Purpose

memory_write

Save a durable fact with an explicit project slug

memory_search

Search excerpts, optionally filtered by project, kind and tags

memory_get

Retrieve one complete memory by ID

memory_update

Correct or expand an existing memory

memory_supersede

Replace outdated knowledge while retaining the old version

memory_list

Browse saved memories

memory_stats

Inspect counts and embedding health

memory_delete

Permanently remove an entry

Kinds: fact, decision, incident, preference, reference, snippet. Use consistent project slugs across clients; global is a convention for cross-project knowledge. Project filters organize retrieval and are not access controls.

Conversation exports

Import extracted conversation exports into a separate, searchable archive without turning historical answers into verified memories. npm run archive:import -- --input /path/to/export --project personal-archive --archive account-one previews offline; add --apply to import. archive_search and archive_get retrieve text through MCP without contacting the original service. Initial support: Claude conversations.json; attachments and other export categories are not indexed. Archive guide and limitations.

Optional Markdown import

Edit the generated, gitignored sources.json:

{
  "claudeProjectsDir": null,
  "projectRoots": [
    { "path": "~/code/my-app", "project": "my-app" }
  ]
}

Each root imports memory/*.md (except MEMORY.md) and dated entries from INCIDENTS.md. Paths may be absolute, ~/…, or relative to sources.json. Set claudeProjectsDir to ~/.claude/projects only if you want to import all local Claude project memory directories as well. Configured project paths map matching Claude directory keys to the same project slug; unknown paths use a best-effort slug.

npm run ingest                  # preview record changes
npm run ingest -- --apply        # apply explicitly

Import tracks files by source and content hash: edits update the existing memory. Missing files are reported, not deleted. Known secret patterns are redacted from imported titles and bodies before embedding and storage; this is a best-effort filter, not a guarantee. Direct MCP writes are not automatically redacted. Import details and note format.

Compatibility

Setup targets macOS, Linux and Windows. Native Windows 11 with Node.js 22.23.4 passed 135 tests and a real-embedding MCP smoke check, using PostgreSQL and Ollama on a Mac through SSH tunnels. Windows Docker Desktop and real assistant sessions remain unverified. See the PowerShell guide for details.

Development and test commands are in CONTRIBUTING.md.

Feedback from your agent

Ask: "Prepare a LocalMCP issue: note import fails" or "I want to suggest a LocalMCP feature." The agent calls feedback_prepare, shows the repository, title and body, then uses feedback_submit after your explicit approval. It returns the created issue URL. Categories are bug, feature and help.

Install GitHub CLI and run gh auth login --hostname github.com in your terminal to enable submission. Credentials are not stored in shared memory. Files and logs are never attached automatically. See feedback setup and limitations.

Privacy and limitations

  • Stored knowledge and embeddings remain on your configured database and embedding endpoints. Retrieved memories are passed to the MCP client and may be sent to its model provider. Agent providers' data policies still apply.

  • This is a local, single-user service. There is no HTTP listener, authentication layer, tenant isolation or encryption at rest. PostgreSQL is bound to loopback; do not expose it publicly.

  • No conversation-history crawler is included. Markdown import and optional hooks are opt-in.

  • Full-text stemming is currently Russian; English identifiers also use exact/fuzzy matching and multilingual embeddings. Search quality depends on your corpus and model.

  • Keep one embedding model and dimension for a database. Dimension mismatches fail without erasing vectors. A same-dimension model change cannot currently be detected; use a separate database for model experiments.

Further reading

License

MIT.

Available Tools

10 tools
feedback_preparePrepare a LocalMCP GitHub issueA

Prepare a bug report, feature request or help request for al-mighty/localmcp. Use only when the user wants to report a LocalMCP problem or suggestion. No network request or automatic log/file collection. Show the complete preview and ask for approval before publishing. Do not use public issues for vulnerabilities or credentials; use SECURITY.md.

Inputs: kind (required), title (required), description (required), steps, +3 more.

feedback_submitPublish an approved LocalMCP GitHub issueA
Idempotent

Publish a feedback_prepare draft under the user's existing gh login. Call only after explicit user approval of that draft's repository, title and body. Never submit automatically after an error or upload private context. Returns the created issue URL. Drafts expire in 15 minutes and belong to this MCP process; do not automatically retry uncertain results.

Inputs: draft_id (required), confirmation (required).

memory_deleteDelete memoryA
Destructive

Permanently remove a memory. Only for entries that were wrong to record at all (secrets, noise, mistakes). For facts that merely became stale, use memory_supersede.

Inputs: id (required).

memory_getGet memoryA
Read-only

Fetch one memory in full by id. memory_search returns only the matching excerpt; call this when the excerpt is not enough and you need the whole text.

Inputs: id (required).

memory_listList memoriesA
Read-only

Browse memories by project/kind/tags without a query. Use to audit what is stored or to load a project's context at the start of a session.

Inputs: kind, tags, limit, project, +1 more.

memory_statsMemory statsA
Read-only

Counts per project and kind, plus embedder and database health. Use to verify the store is reachable and to see what knowledge exists before searching blindly.

Inputs: no named parameters.

memory_supersedeSupersede memoryA

Replace an outdated memory with a new one, keeping the old version queryable so the history of the belief survives. Prefer this over delete whenever a fact changed.

Inputs: id (required), body (required), kind (required), title (required), +4 more.

memory_updateUpdate memoryA

Amend an existing memory in place. Use for corrections and additions that do not change what the memory is about; use memory_supersede when the belief itself changed.

Inputs: id (required), body, tags, title, +2 more.

memory_writeWrite memoryA

Persist one durable fact. Use for: non-trivial fixes and their root cause (kind=incident), architectural choices and why (decision), stable project facts (fact), how the user wants to be worked with (preference), external URLs/dashboards/tickets (reference), reusable code patterns (snippet). Do NOT store what the repo or git history already records. Near-duplicates are rejected with the existing id — update or supersede that instead.

Inputs: body (required), kind (required), title (required), project (required), +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: memory search/get/list cover retrieval, write/update/supersede/delete cover mutation with explicit guidance on when to use which, and feedback prepare/submit form a clear staged workflow. The descriptions explicitly contrast easily confused operations such as update vs supersede and delete vs supersede.

    Naming Consistency5/5

    All tools follow a consistent snake_case resource_action pattern: memory_* for memory operations and feedback_* for feedback operations. The naming is predictable and readable throughout.

    Tool Count5/5

    Ten tools is well-scoped for a local memory server with a small feedback path. The eight memory tools each cover a distinct lifecycle operation, and the two feedback tools are appropriately minimal.

    Completeness4/5

    The memory surface is strong, covering search, retrieval, listing, stats, creation, correction, supersession, and deletion. The feedback path covers preparation and submission but lacks status tracking, listing, or follow-up operations, which is a minor gap for the stated reporting purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Provides AI coding agents with a local-first persistent memory layer they can read and write during sessions, storing decisions, preferences, error patterns, and research per project or globally. Enables semantic and keyword search, formatted context recall, and cross-project guideline surfacing without API keys or cloud storage.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Gives AI coding agents a local-first persistent memory they can read and write directly during sessions, storing decisions, preferences, error patterns, and guidelines in per-project and global SQLite stores. Enables semantic and keyword retrieval of relevant context across sessions so agents start work already knowing a codebase's conventions and history.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to store and retrieve persistent project and cross-project memories via semantic search, so decisions, preferences, error patterns, and guidelines survive across sessions. Optionally supports autonomous task execution built on the same local-first knowledge store.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to read and write persistent memory directly during sessions, storing decisions, preferences, error patterns, research, and cross-project guidelines in local SQLite databases. Supports semantic search so relevant project and global context can be recalled by meaning, fully offline and without API keys.
      -