An MCP server that gives an agent a persistent memory: vector search over PostgreSQL (pgvector), a knowledge graph (Apache AGE) and 29 tools to write, read, connect and forget.
- Hybrid retrieval — vector similarity and full-text search, so both paraphrases and exact identifiers are found.
- Scoped — a global scope for what is true everywhere, a project scope per codebase.
- Self-cleaning — contradictions are detected and the outdated fact is superseded automatically.
- One answer shape — every tool returns the same envelope, so an agent never has to guess.
cp .env.example .env
# Required: set POSTGRES_PASSWORD and MCP_AUTH_TOKEN (see the comments in
# .env.example; generate each with: python -c "import secrets; print(secrets.token_urlsafe(32))")
docker compose up -dThat starts three services:
| Service | Port | Description |
|---|---|---|
| PostgreSQL | 127.0.0.1:5432 |
User/DB from .env (memory/memory by default), password from POSTGRES_PASSWORD |
| Inference API | 127.0.0.1:8001 |
Embeddings (local; GPU when available, CPU fallback) + NLI (configurable LLM) |
| Loci MCP | 127.0.0.1:8766 |
The MCP server (Streamable HTTP, bearer-token protected) |
Authentication. The HTTP transport exposes every tool, including
drop_projectandprune_memories. Every request must sendAuthorization: Bearer <MCP_AUTH_TOKEN>; the server refuses to start on a non-loopback bind without a token. Ports are published on loopback only by default. To reach the server from another machine, change the mapping to"8766:8766"and keep the token set.Contradiction detection needs a configured LLM provider and is off by default (
LLM_PROVIDER=none). SetLLM_PROVIDERtogroq,openai,anthropic,ollama,openai-compatibleorautoto enable it. Embeddings always run locally: the image uses an NVIDIA GPU when Docker exposes one and falls back to CPU otherwise. See GPU acceleration.Data egress.
groq,openaiandanthropicare hosted providers: when a contradiction check runs, the compared memory content is sent to them. Useollama/openai-compatiblewith a local endpoint (orLLM_PROVIDER=none) to keep memory content on this machine.server_healthreports the active provider and whether it is external (data_egress).# Requires a driver and the NVIDIA Container Toolkit docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
{
"mcpServers": {
"loci": {
"type": "streamable-http",
"url": "http://localhost:8766",
"headers": {
"Authorization": "Bearer <MCP_AUTH_TOKEN>"
}
}
}
}Works with Cursor, Windsurf, Copilot, VS Code (Cline / Roo Code / Continue) and Zed. Setup for each client, plus the stdio variant for Claude Code, is in docs/clients.md.
Write
| Tool | What it does |
|---|---|
remember |
Store a fact, decision or learning (auto-embedded, deduplicated) |
remember_batch |
Store many facts at once |
update_memory |
Change content, importance, metadata, entity, type or TTL; touch=true refreshes recency, restore=true undoes a soft delete |
update_batch |
Update many memories in one call |
merge_memories |
Fold 2-20 active memories of one scope into one new fact, superseding every source |
forget |
Soft delete or hard delete, by id, entity, metadata filter or content match |
Read
| Tool | What it does |
|---|---|
recall |
Hybrid vector + full-text search with ranking, decay and graph boost |
recall_batch |
Several independent searches in one call (multi-intent turns) |
compile_context |
One token-bounded context block assembled from ranked memories |
list_memories |
Browse memories without a query (filter, sort, page); memory_id fetches one, including hidden rows |
get_entity |
Everything known about one entity |
get_entities |
Batch lookup of 1-25 entities in one call |
list_entities |
Browse the entities of a scope |
list_projects |
Discover every scope (project name, tables, graph, counts) |
init_context |
Session bootstrap: recent memories plus project_stats for every scope |
Graph
| Tool | What it does |
|---|---|
relate / relate_batch |
Create relations between entities |
unrelate |
Remove a relation, optionally keeping its context sentence |
find_connections |
Traverse the graph from an entity (paged) |
find_paths |
Shortest path between two entities |
list_relations |
Browse edges without a start entity (paged) |
Maintenance
| Tool | What it does |
|---|---|
contradictions_report |
Find conflicting memories, per entity or scope-wide; resolve="newest", resolve_min_confidence, dry_run |
export_memories / import_memories |
Backup and restore, including the graph |
verify_integrity |
Find and repair dangling supersede links |
prune_memories |
Permanently remove expired/forgotten rows (active memories never touched; dry_run by default) |
drop_project |
Remove a project scope completely |
server_health |
Check Postgres and the inference API |
MCP_TOOLSET=core exposes only the 17 daily read/write/graph tools; the
default full exposes all 29.
There is also one resource, memory://stats, with the memory, entity and
relation counts plus the health of the services.
Every parameter is documented in the tool's own JSON schema. The full reference is in docs/tools.md; for agents there is AGENTS.md.
Memory types. remember takes a mem_type that decides how a fact is
used later: fact (default), decision, learning, preference, pattern,
incident, runbook, context, observation, convention, command or
note. Other values are rejected (MEMORY_TYPES in config.py).
One envelope. Every tool answers with
{"ok", "status", "id", "error", "warnings"} plus count/results for
collections. A failed call never raises — it returns ok: false with the
reason, even for an invalid argument.
Two scopes. Facts live either in the global scope (true everywhere) or in a project scope. A project search sees both, so global facts stay visible inside a project. See docs/scopes.md.
Recency without forgetting. Memories fade with a 90-day half-life, but
recency may only take 30% of the ranking score — semantics always win.
min_decay_score filters for "only fresh and important".
Contradictions clean themselves up. With check_contradictions=true a new
fact is compared against the nearest active memories of its scope; a
contradiction supersedes the old one automatically. Entity tagging is not
required: with an entity, its memories get the candidate seats first, without
one all memories compete (the answer reports contradictions.cross_entity).
The bootstrap is not a search. init_context returns the most recently
changed memories, so a fact the agent just stored is always there.
How a query becomes a ranked list — and what every score field means — is documented in docs/retrieval.md.
A three-line example:
init_context(project="api")
recall(query="deployment rollback procedure", project="api", include_decay=true)
remember(content="The API runs on Postgres", entity="API", project="api")
| Env Var | Default | Description |
|---|---|---|
MEMORY_DATABASE_URL |
postgresql://memory@localhost:5432/memory |
Postgres DSN (supply the password here) |
POSTGRES_PASSWORD |
- (required by compose) | Password for the bundled Postgres; also used to build the DSN |
POSTGRES_USER / POSTGRES_DB |
memory |
Bundled Postgres user and database |
MEMORY_INFERENCE_URL |
http://localhost:8001 |
Inference API |
MCP_TRANSPORT |
stdio |
stdio, sse or streamable-http |
MCP_HOST |
0.0.0.0 |
Bind address (sse/streamable-http only) |
MCP_PORT |
8766 |
Port (sse/streamable-http only) |
MCP_AUTH_TOKEN |
- (required for HTTP) | Bearer token every HTTP request must send |
MCP_ALLOW_INSECURE_HTTP |
false |
Allow an unauthenticated non-loopback HTTP bind (sandbox only) |
INFERENCE_DEVICE |
auto |
auto (CUDA when available), cpu or cuda |
LLM_PROVIDER |
none |
groq, openai, anthropic, ollama, openai-compatible, auto or none; none disables NLI (egress is opt-in) |
LLM_MODEL |
provider default | NLI model |
LLM_REASONING_EFFORT |
low for Groq/gpt-oss |
Reasoning budget (low/medium/high; none disables) |
LLM_API_KEY |
– | Generic key; overrides the provider-specific key |
LLM_BASE_URL |
provider default | Base URL for OpenAI-compatible or Ollama endpoints |
GROQ_API_KEY / GROQ_MODEL |
– | Groq key and model (backwards compatible) |
OPENAI_API_KEY |
– | Used when LLM_PROVIDER=openai |
ANTHROPIC_API_KEY |
– | Used when LLM_PROVIDER=anthropic |
OLLAMA_BASE_URL |
http://host.docker.internal:11434/v1 |
Ollama endpoint |
All providers, the scoring constants and the inference API are documented in docs/configuration.md.
| Page | Content |
|---|---|
| docs/tools.md | Every tool, every parameter, the envelope, typical workflows |
| docs/retrieval.md | How a query becomes a ranked list; scores, decay, contradictions |
| docs/scopes.md | Global vs. project scopes, project names, project lifecycle |
| docs/backup.md | Export and import, including the graph |
| docs/configuration.md | Env vars, LLM providers, Docker, inference API, constants |
| docs/clients.md | Editor and agent client setups |
| docs/architecture.md | Schema, direct SQL, module map, request flow |
| AGENTS.md | The dense machine-facing contract for agents |
pip install -r requirements-dev.txt
python -m pytest # integration tests against an isolated test databaseThe tests create and drop a loci_test database and run a local fake
inference server, so no LLM key is needed. The module map is in
docs/architecture.md.
Apache 2.0 — see LICENSE.