memory-core
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
memory-core
A self-hosted, database-backed long-term memory for AI agents.
Your agent's memories live in Postgres as small Markdown notes. memory-core serves them over REST and MCP (Model Context Protocol) with hybrid search, per-client tokens, version history, and a secret scanner on every write. It was built to give Claude Code one shared memory across several machines, but any MCP client or HTTP caller can use it.
Status: a personal project that runs one household's agent memory every day. It is small (about 2,000 lines of Python), tested, and opinionated. It is shared as-is: expect to read the code, and expect rough edges outside the author's setup (Docker Swarm, Windows clients).
What it does
Hybrid search. BM25 keyword search (pg_textsearch) and vector search (pgvector) are merged with reciprocal rank fusion, then re-scored by a cross-encoder. Exact strings such as IPs and model ids work as well as plain-language questions.
An empty answer when there is no answer. A score floor drops weak hits, so an off-topic question returns nothing instead of five plausible-looking wrong notes.
Local models. Embedding and rerank models are baked into the image and run on CPU. No memory text leaves the host.
Scoped bearer tokens. One token per client, each revocable alone:
read,suggest(writes are queued for review),write,admin. Only a SHA-256 hash of each token is stored.Owner isolation. Postgres row-level security scopes every query to the token's owner.
Secret scanning. A write that contains an API key, private key, JWT or password-like assignment is rejected. Store a pointer (
secret:NAME) instead of the value.Versioning. Every change is kept in a history table. Writes accept
expected_versionfor optimistic locking, and any version can be restored.Markdown in, Markdown out. Import a folder of
.mdfiles with YAML front matter, and export back to the same format on a schedule.Claude Code hooks (optional): automatic recall on each prompt, a read-only local mirror of the memories, and an offline outbox for when the server is unreachable.
Related MCP server: HAM
How it fits together
MCP client / REST caller
│ Authorization: Bearer mc_<name>_<random>
▼
api (FastAPI + FastMCP, port 8020)
│ embed query → BM25 + vector → RRF → cross-encoder rerank → score floor
▼
db (Postgres 17 + pgvector + pg_textsearch, row-level security)Service in | What it does |
| Postgres 17 with pgvector and pg_textsearch. Data lives in the volume |
| One-shot job: applies migrations, creates or rotates the |
| uvicorn on port 8020. REST under |
| Exports one owner's memories to Markdown every hour (optional). |
| Daily |
Quick start
You need Docker with Swarm mode on (docker swarm init is enough for a single host). The stack
uses Swarm secrets, so no password ever sits in a file or an environment variable.
1. Create the secrets.
python -c "import secrets;print(secrets.token_urlsafe(32))" | docker secret create memcore_db_admin_password -
python -c "import secrets;print(secrets.token_urlsafe(32))" | docker secret create memcore_db_app_password -
docker secret create memcore_tls_cert fullchain.pem # leaf certificate first, then intermediates
docker secret create memcore_tls_key privkey.pemNo TLS certificate yet? Remove the two MC_TLS_* lines and the two TLS secrets from the api
service and it serves plain HTTP. Only do that behind a TLS-terminating proxy or on a network you
fully trust: the bearer tokens travel in a header.
2. Deploy.
Edit docker/stack.yml first: set the exporter's --owner and its bind-mount path (the folder
must exist), or delete the exporter service.
docker stack deploy -c docker/stack.yml memory-core
curl https://<host>:8020/healthz # -> {"status":"ok"}The images are built by .github/workflows/publish.yml. The app image is large because the
models are baked in, and the first start takes a moment while they load.
3. Mint a token. The token is printed once and cannot be shown again.
docker exec $(docker ps -q -f name=memory-core_api) \
python -m app.cli token create --name my-laptop --owner alice --scope writetoken list and token revoke --name <name> work the same way. --owner is the tenant: tokens
with the same owner share one set of memories, and can never see another owner's.
4. Connect a client. For Claude Code:
claude mcp add --transport http memory-core https://<host>:8020/mcp/ \
--header "Authorization: Bearer <token>"Keep the trailing slash on /mcp/.
MCP tools
Tool | Scope | What it does |
| read | Hybrid search. Returns the best-matching passages with their memory keys. |
| read | One full memory, by key or by name. |
| read | All memories; filter by |
| read | The version list for one memory. |
| suggest | Create or replace a memory. With a |
| write | Replace one exact string in a memory's body. It must match exactly once. |
REST API
Every call needs Authorization: Bearer <token>, except /healthz.
Method and path | Scope | Notes |
| read | Body: |
| read | Query: |
| read | 404 if the key does not exist |
| suggest | Create or replace. Optional |
| write | Body: |
| read | Version list |
| read | That version's full snapshot |
| write | Body: |
A rejected secret returns HTTP 422 with the kind of secret found, never the value.
A memory
A memory is a key, a name, a short description, an optional type, and a Markdown body. As a file:
---
name: Guest wifi
description: network name and where the password lives
metadata:
type: reference
---
## Current state
The guest network is `house-guest`. Password: secret:GUEST_WIFI (in the password manager).The key is the filename stem (reference_guest_wifi). Bodies are split into chunks by heading,
and each chunk is embedded together with the memory's name and description.
Configuration
Server settings are environment variables on the api and migrate services.
Variable | Default | Meaning |
|
| Where Postgres is |
|
| Embedding model. The api refuses to start if these differ from what the database was created with |
|
| Cross-encoder. Empty turns rerank off |
|
| Candidates fetched from each of BM25 and vector search |
|
| How many fused candidates are reranked |
| model default | Token cap for the cross-encoder input |
|
| Score floor when rerank is on |
|
| Score floor when rerank is off |
| unset | Set both to serve HTTPS |
The score floors depend on your data and your rerank model. The value in docker/stack.yml was
tuned on the author's memories; tune yours with the eval tool below.
Import and export
Import a folder of Markdown memories through the API. Each write is authenticated, secret-scanned and versioned, and running it again changes nothing:
export MC_IMPORT_TOKEN=<a write token>
python -m app.importer --dir ./memory --url https://<host>:8020A rejected entry means the secret scanner found a value. Replace it with a pointer. If it is a
false positive, add it as a SAFE case in tests/test_secret_scan.py and fix the pattern.
Export runs as the exporter service, or by hand: python -m app.cli export --owner alice --out ./export.
Claude Code integration (optional)
The files in hooks/ are Claude Code hooks. They use only the Python standard library and read
their settings from ~/.memory-core/.env (override the path with MC_ENV_FILE).
Client variable | Meaning |
| Base URL of the server, e.g. |
| A |
| A |
|
|
| The local memory folder. Default |
| Where hooks write logs and the outbox. Default |
|
|
Hook | Event | What it does |
| UserPromptSubmit | Searches for the prompt and hands Claude the top 3 hits. Fails silently |
| PostToolUse |
|
| PreToolUse |
|
| PostToolUse |
|
| — | Queues a save while the server is unreachable; replayed later with a version check |
Two modes. In files mode the Markdown folder is the master and python -m app.sweep keeps
the server in step with it. In db mode the database is the master and python -m app.downsync
writes a read-only Markdown mirror, so plain grep still works when the server is down.
scripts/register-sweep-task.ps1 and scripts/register-downsync-task.ps1 register these as
Windows scheduled tasks; on Linux or macOS use cron or a systemd timer.
scripts/mint_to_env.py mints a token over SSH and writes it straight into the env file without
printing it. scripts/health_line.py prints a one-line health summary for a daily report.
Measuring search quality
eval/queries.json is a small sample. Replace it with real questions about your own memories:
plain-language questions, exact identifiers, and "noise" questions that should return nothing.
export MC_EVAL_TOKEN=<a read token>
python eval/run_eval.py --url https://<host>:8020 --label baseline
python scripts/bench.py https://<host>:8020 # p50 / p95 search latencyrun_eval.py reports Recall@1/3/5 and MRR for each set and how many noise queries wrongly
returned a hit. Use it whenever you change a model or a score floor.
Security notes
Built for a private network. Run it on a LAN or VPN, or behind a reverse proxy. It has no rate limiting and has not been hardened for the open internet.
DNS-rebinding protection is off in the MCP transport (
app/api.py), because every call is bearer-authenticated and the service is meant to be reached by several hostnames. Turn it back on if you expose the server more widely.Tokens are shown once. Only their hashes are stored. Keep them out of repositories and tracked settings files, and give each client its own so one can be revoked alone.
The secret scanner is a safety net, not a guarantee. It matches known patterns.
/healthzis unauthenticated and returns only{"status":"ok"}.
Found a security problem? Please open a GitHub issue. Leave out anything sensitive, and ask for a private channel if you need one.
Development
Tests need a throwaway Postgres with both extensions. docker/dev-db.yml starts one on port 5433:
MC_DEV_DB_PASSWORD=<pick one> docker stack deploy -c docker/dev-db.yml memory-core-dev
pip install -r requirements-dev.txt
export MC_TEST_ADMIN_URL=postgresql://postgres:<that password>@localhost:5433/postgres
python -m pytestEach test run creates its own database and drops it afterwards. Tests use a fake 8-dimension
embedder; set RUN_REAL_MODELS=1 to also run the tests that download the real models.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Hosted persistent memory with semantic search, importance and TTL for AI agents.
Persistent cloud memory for AI agents. Store and search key-value memories across sessions.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAccess control, conflict resolution, and audit for shared agent memory. Policy-gated memory tools over Postgres + pgvector, exposed via MCP.1Apache 2.0

HAMofficial
AlicenseNot gradedqualityCmaintenanceProvides persistent, scoped shared memory for collaborating AI agents, with tools for storing observations, semantic recall, and handoff workflows. Backed by PostgreSQL and exposed through MCP.1Apache 2.0- FlicenseAqualityCmaintenanceEnables AI agents to persist, search, and query shared memories in PostgreSQL through hybrid retrieval, preset answers, and AI-to-AI consultation via MCP.9-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to persist, retrieve, and share source-linked memory across sessions via MCP tools, backed by PostgreSQL with project/session management, decision tracking, keyword search, and cross-host context handoff.Apache 2.0