LocalMCP
LocalMCP is a shared persistent memory store for coding agents, with tools to manage memories and prepare/approve GitHub feedback.
Save durable memories such as facts, decisions, incidents, preferences, references, and snippets under project slugs with tags, source, and importance.
Search memories with hybrid semantic + lexical search, filtered by project, kind, tags, limit, and superseded status.
Retrieve a complete memory by ID, list/browse memories, and inspect counts plus database/embedding health.
Update memories in place, supersede outdated memories while keeping history, or permanently delete wrong/noise entries.
Prepare bug, feature, or help GitHub issue drafts and submit them only after explicit user approval using an existing GitHub CLI login.
Prepares and submits user-approved bug reports, feature requests, and help requests to the project's GitHub Issues, returning the created issue URL.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@LocalMCP Save a decision under project demo: use pgvector for semantic search."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
Client | Codex or Claude Code supporting local stdio MCP servers |
Local ports |
|
Internet | Required to download code, packages, the database image and model; GitHub connectivity is needed to submit issues |
Issue submission — optional | GitHub CLI ( |
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 doctorIf 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 |
| Save a durable fact with an explicit project slug |
| Search excerpts, optionally filtered by project, kind and tags |
| Retrieve one complete memory by ID |
| Correct or expand an existing memory |
| Replace outdated knowledge while retaining the old version |
| Browse saved memories |
| Inspect counts and embedding health |
| 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 explicitlyImport 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 toolsfeedback_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 issueAIdempotent
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 memoryADestructive
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 memoryARead-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 memoriesARead-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_searchSearch memoryARead-only
Hybrid semantic + lexical search over persistent cross-project memory. Call this BEFORE answering questions about past decisions, incidents, infrastructure quirks, or user preferences — it is the source of truth for things not derivable from the current repo.
Inputs: query (required), kind, tags, limit, +2 more.
memory_statsMemory statsARead-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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Persistent memory for AI agents. Search, store, and recall across sessions.
Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceProvides 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.-
- FlicenseNot gradedqualityAmaintenanceGives 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.-
- FlicenseNot gradedqualityAmaintenanceEnables 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.-
- FlicenseNot gradedqualityAmaintenanceEnables 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.-