# 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](https://modelcontextprotocol.io/) 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](README.ru.md) · [Client setup](docs/clients.md) · [Architecture](docs/architecture.md) · [Credentials](docs/credentials.md) · [Contributing](CONTRIBUTING.md)

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.

- [x] Share one persistent store across multiple MCP clients and sessions.
- [x] Save facts, decisions, incidents, preferences, references and snippets.
- [x] Search by meaning and words, with project, kind and tag filters.
- [x] Return short search excerpts and retrieve complete memories separately.
- [x] Update, supersede with history retained, and delete memories.
- [x] Detect near-duplicate writes when embeddings are available.
- [x] Import Markdown incrementally from configured directories, with a change preview.
- [x] Continue lexical search while Ollama is unavailable and fill missing vectors after recovery.
- [x] Provide optional prompt-time recall for Claude Code through manually configured hooks.
- [x] Diagnose database connectivity and embedding availability.
- [x] Prepare and publish user-approved bug reports, feature requests and help requests to the project's GitHub Issues.

## 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](docs/clients.md) for registration details and a cross-client sharing example.

## Manual setup

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

```bash
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:

```bash
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](docs/clients.md) 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**.

## Optional Markdown import

Edit the generated, gitignored `sources.json`:

```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.

```bash
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](docs/architecture.md#markdown-import).

## 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](docs/windows.md) for details.

Development and test commands are in [CONTRIBUTING.md](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](docs/feedback.md).

## 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

- [Client configuration and optional hooks](docs/clients.md).
- [Backups, restore and troubleshooting](docs/operations.md).
- [OS credential access through a local helper](docs/credentials.md).
- [Security and data handling](SECURITY.md).

## License

[MIT](LICENSE).