Skip to main content
Glama

memory-core

One shared, self-hosted long-term memory for every AI coding agent you run.

ci MCP Postgres + pgvector llama.cpp License: MIT

The Brain view running on generated demo data (?demo): each dot is a memory, clusters are project branches, and a recall lights up its hits.


Claude Code, Codex, Aider and anything else that speaks MCP (or can run a shell command) read from and write to the same memory: facts about your projects, servers, decisions and gotchas, plus a library of skills, docs and saved references. Start a session in any agent on any machine and it already knows what the last one learned.

It is built to run on a small always-on box (a home server, a mini PC, a cheap VPS) with no LLM on it. Agents send finished facts. The server redacts secrets, embeds the facts on the CPU and stores them in Postgres with pgvector.

  • Agent-agnostic: any MCP client works over HTTP, and anything with a shell can use the mc CLI or REST.

  • Cheap to run: three containers, about 2.5 GB of RAM, CPU only.

  • Private by default: every port binds to 127.0.0.1. You choose how to expose it (Tailscale, a reverse proxy).

  • Multilingual: recall works across English and Indonesian out of the box (the embedding model is multilingual, and the keyword stop-word list covers both).

NOTE

memory-core runs day to day with four agents across two machines and a few thousand memories. Expect a working, opinionated tool rather than a polished product: some features (the live view, phone capture) assume Tailscale.

Why

Each agent session starts from zero. Agents rediscover the same port numbers, re-debug the same quirks and forget decisions made a week ago. Per-tool memory files (CLAUDE.md, AGENTS.md) don't carry over between tools or machines, and they grow until nobody reads them. memory-core is one store every agent shares. It hands each agent only the few memories that fit the prompt in front of it.

Related MCP server: Cortex

How it works

A session, end to end

sequenceDiagram
    autonumber
    participant U as You
    participant A as Agent (Claude Code)
    participant H as Hook
    participant M as memory-core
    U->>A: open a session in ~/projects/foo
    H->>M: profile + last 3 episodes of project:foo
    M-->>A: who you are, projects, where you left off
    U->>A: "why does the server freeze again?"
    H->>M: recall(prompt)
    M-->>H: top hits + shared rare words
    H-->>A: inject only hits that pass the bar
    A->>M: memory_recall / library_search when it needs more
    Note over A: does the work
    A->>M: memory_remember(["fact", "fact"])
    M-->>A: saved · related #1646 · or held as near-duplicate
    A->>M: episode: what changed, what is left, where

The hook injects nothing unless a memory shares a rare word with the prompt and clears a similarity bar. That keeps the context small: on 131 hand-labelled prompts it kept 87% of the relevant lines and 20% of the noise.

Recall: what gets ranked first

flowchart LR
    Q[query] --> FT[full-text search<br/>prefix match, top 50]
    Q --> VS[vector search<br/>cosine, top 50]
    FT & VS --> S["score = cosine + 0.15 × share of the query's<br/>rare-word weight (IDF) the memory contains"]
    S --> T[tie-breaks: verified facts,<br/>current project]
    T --> L[follow links one step<br/>from the top 3 hits]
    L --> R[results with who wrote them,<br/>when, verified or not]

Remember: what happens to a new fact

flowchart TD
    F[agent sends a fact] --> X[redact secrets<br/>keys, tokens, bearer headers]
    X --> E[embed on CPU]
    E --> D{closest live memory}
    D -->|identical| SK[skip]
    D -->|"cosine ≥ 0.92"| HD[hold: agent supersedes<br/>the old one or forces]
    D -->|"0.70 – 0.92"| RL[save + return the older one<br/>as related, since updates land here]
    D -->|"< 0.70"| SV[save]
    RL & SV --> LK[link: related / saved together / explicit]

Nothing is ever deleted: forget and supersede set valid_to, so the history stays queryable.

The UI

A React page served at /live, visible only to allow-listed Tailscale logins. No token lives in the browser.

Live: every tool call from every agent as it happens. Each call runs along its agent's connector into the memory bank, and the live feed lists them with latency and results.

Brain: every memory as a neuron, one cluster per branch around the core notes, links drawn as axons. Click a neuron to read it and walk its links, or filter by branch or text.

Screenshots use generated demo data. Run cd web && npm run dev and open /live/?demo to see the same.

Library (not pictured, since it holds personal data): search skills, starred repos and project docs, and review saved screenshots and links in an inbox.

Features

Hybrid recall

Keyword + meaning, tuned on a real question set (see below).

Dedupe on write

Near-duplicates are held back, likely updates come back as related.

Secret redaction

API keys, tokens and bearer headers become [REDACTED:kind] before storage or logging.

Scopes and tokens

global, project:<name>, agent:<id>, session:<name>. Each agent token carries fnmatch patterns that limit what it reads and writes.

Branches

Projects grouped into domains (work, study, infra…) from app/domains.json or filed by agents themselves. scope='domain:<name>' searches one.

Links

related by meaning, together when saved in one call, explicit when an agent says so. Recall follows them one step.

Library

Skills (SKILL.md folders), starred GitHub repos and project docs, content-addressed. Agents can search them, read one file or pull a whole skill folder on demand.

Saved references

Screenshots and links from the web app or a phone Shortcut, OCR'd and kept in an inbox until an agent files them.

Live view

The page above, over server-sent events.

Architecture

flowchart LR
  subgraph Agents
    CC[Claude Code<br/>MCP + hooks]
    CX[Codex<br/>MCP]
    AD[Aider / scripts<br/>mc CLI]
  end
  subgraph Server["Home server · docker compose · ports on 127.0.0.1"]
    APP[app :8420<br/>MCP /mcp · REST /api/v1 · /live]
    PG[(Postgres 17<br/>+ pgvector)]
    EMB[llama.cpp :8421<br/>Qwen3-Embedding-0.6B]
  end
  CC & CX -->|MCP + bearer token| TS[Tailscale serve]
  AD -->|REST + bearer token| TS
  Browser[Browser on tailnet] -->|Tailscale login| TS
  TS --> APP
  APP --> PG
  APP --> EMB
  • One ASGI app (app/server.py, Starlette + the MCP SDK) serves MCP, REST and the live page.

  • No LLM on the server. Writing a good fact needs a model, and the agent already has one. The server only embeds, ranks and stores.

  • CPU only. The embedder runs at about 230 tokens/s on an i3, so there is deliberately no reranker.

Recall quality

scripts/eval_recall.py runs a question set through the real recall path and reports hit@k and MRR. The questions are phrased the way a person actually asks (mixed Indonesian and English), and each lists the memory ids that answer it.

Corpus

Questions

hit@1

hit@5

hit@10

MRR@10

median latency

2,626 memories from real use (13 Nov 2026)

102

0.716

0.951

0.98

0.814

168 ms

This beat the reciprocal-rank fusion used before (hit@1 0.50), which had decayed as the corpus grew because common-word keyword matches crowded the keyword list. That set refers to private memories, so the repo ships only an example of the format (tests/eval/recall_questions.json). The agent that knew the memories wrote the questions, so treat the numbers as a regression check, not a benchmark.

MCP tools

Memory

Library

memory_profile: who you are, projects by branch, recent sessions

library_search: skills, repos, docs, references

memory_recall: hybrid search, optional scope / domain:

library_categories: the shelves and when to use each

memory_remember: save facts, supersede, link

library_get / library_file: read an item or one file in pages

memory_forget: retire a memory with a reason

library_inbox / library_view / library_review: file saved references

memory_timeline: session episodes, newest first

memory_branches / memory_branch / memory_branch_review

REST mirrors them under /api/v1/{profile,recall,remember,forget,timeline} and /api/v1/library/* with the same token.

Clients

  • Claude Code hooks (clients/claude_code_hook.py): injects the profile and the project's last episodes at session start and matching memories on each prompt. It never injects the same memory twice in a session, and it can pull a matching skill into ~/.claude/skills for that session only.

  • Save checkpoint (clients/claude_code_checkpoint.py): a Stop hook. After real work with nothing saved, it asks the agent once to save durable facts and an episode.

  • mc CLI (clients/mc.py, stdlib only): profile, recall, remember, library search, skill pull/drop. For agents without MCP and for scripts.

  • Library sync (clients/library_sync.py): scans a machine's skills, docs and GitHub stars. It sends a manifest of hashes and uploads only what the server lacks.

Quick start

Requirements: Docker with compose, and about 2.5 GB of RAM for the three containers (their memory limits). Tailscale is optional; without it, the MCP and REST API still work behind any reverse proxy, but the live view and phone capture (which authenticate by Tailscale login) stay closed.

git clone https://github.com/GodrezJr2/memory-core && cd memory-core
mkdir -p data/media data/bundles models
openssl rand -hex 24 > data/pg_password
echo '{"agents": {}}' > data/tokens.json
sudo chown -R 65534 data/media data/bundles      # the app container runs as nobody

# embedding model (~640 MB)
curl -L -o models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  https://huggingface.co/Qwen/Qwen3-Embedding-0.6B-GGUF/resolve/main/Qwen3-Embedding-0.6B-Q8_0.gguf

python3 scripts/mint_token.py claude-laptop --file data/tokens.json   # prints the token once
docker compose up -d --build
tailscale serve --bg --https=8420 http://127.0.0.1:8420             # optional: reach it from your tailnet

Check it is up with curl http://127.0.0.1:8420/healthz, then mint one token per agent.

Connect an agent

Claude Code:

claude mcp add --transport http memory https://<your-host>.ts.net:8420/mcp \
  --header "Authorization: Bearer <token>"

Codex (~/.codex/config.toml) and other MCP clients take the same URL and bearer header. For agents without MCP:

export MC_URL=https://<your-host>.ts.net:8420 MC_TOKEN=<token>
python clients/mc.py recall "which port does the api run on"
python clients/mc.py remember "The API runs on port 8080." --scope project:api

The hooks make memory automatic: context at session start, relevant memories on each prompt, and a nudge to save before the session stops. Copy them into ~/.claude/hooks/:

mkdir -p ~/.claude/hooks
cp clients/claude_code_hook.py ~/.claude/hooks/memory_context.py
cp clients/claude_code_checkpoint.py ~/.claude/hooks/memory_checkpoint.py
cp clients/mc.py ~/.claude/hooks/mc.py          # lets the hook pull matching skills

and register them in ~/.claude/settings.json (they read the URL and token from the memory MCP entry above):

{
  "hooks": {
    "SessionStart":     [{ "hooks": [{ "type": "command", "command": "python3 ~/.claude/hooks/memory_context.py" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "python3 ~/.claude/hooks/memory_context.py" }] }],
    "SessionEnd":       [{ "hooks": [{ "type": "command", "command": "python3 ~/.claude/hooks/memory_context.py" }] }],
    "Stop":             [{ "hooks": [{ "type": "command", "command": "python3 ~/.claude/hooks/memory_checkpoint.py" }] }]
  }
}

Configuration

Environment variables of the app service (compose.yaml):

Variable

Default

What it does

DATABASE_URL

built from PG_HOST and the pg_password secret

Postgres connection string

PG_HOST

postgres

Postgres host when DATABASE_URL is unset

EMBED_URL

http://embedder:8421

OpenAI-compatible embeddings server

TOKENS_FILE

/data/tokens.json

agent tokens (SHA-256 hashes only), written by scripts/mint_token.py

NEAR_DUPLICATE

0.92

cosine at or above which a new fact is held as a near-duplicate

RELATED

0.70

cosine at or above which the older memory comes back as related

CANDIDATES

50

rows taken from each of keyword and vector search

LIVE_VIEWERS

empty

comma-separated Tailscale logins allowed to open /live

MEDIA_DIR

/data/media

images of saved references

BUNDLE_DIR

/data/bundles

skill folders stored as zips

Files to make your own:

  • compose.yaml: LIVE_VIEWERS and the data paths.

  • app/domains.json: your own branches (the example ships study, work, projects, infra and personal). Their names also pick the Brain view's colours in web/src/index.css and web/src/lib/brain.ts.

  • app/library_categories.json: the library shelves. It ships as an example: 18 shelves with the descriptions new items are matched against, generic guides, and a few sample entries. Pin your own skills and starred repos to shelves under skills and repos, and write each shelf's guide for your agents.

  • The INSTRUCTIONS text in app/server.py, which MCP clients show their agent.

Swapping the embedder

Any OpenAI-compatible /v1/embeddings server works (another llama.cpp model, Ollama, TEI, vLLM, a hosted API): set EMBED_URL. Three things are tied to Qwen3-Embedding-0.6B:

  1. Dimension: app/schema.sql declares vector(1024) in three tables. A model with another size needs those changed and every memory re-embedded.

  2. Query prompt: app/embed.py prefixes queries with Instruct: …\nQuery: (documents go in as-is). Use whatever your model's card asks for.

  3. Thresholds: cosine spreads differ between models. Recalibrate NEAR_DUPLICATE (0.92) and RELATED (0.70), both env vars, plus the hook's injection bars, and check the result with scripts/eval_recall.py.

Development

pip install -r requirements.txt pytest
python -m pytest tests                 # 94 rule tests, no services needed
cd web && npm ci && npm run dev        # live view; open /live/?demo for generated traffic
MC_URL=... MC_TOKEN=... python scripts/smoke.py   # 46 end-to-end checks against a running server
app/        server, store (SQL + ranking), rules (scopes, redaction), library, refs, activity feed
clients/    Claude Code hooks, mc CLI, library sync
scripts/    token minting, backup, recall eval, near-duplicate finder, skill update check, smoke test
tests/      unit tests and the eval set format
web/        live view: React 19, Tailwind 4, Framer Motion, d3-force
docs/       README images

Operating

  • Backups: scripts/backup.sh writes a pg_dump (without the access log) to $BACKUP_DIR and keeps 14 days; run it from cron.

  • Safe deploys: tag the running image before rebuilding (docker tag memory-core:local memory-core:prev), then build, docker compose up -d app, wait for the health check and run scripts/smoke.py. If anything fails, tag prev back and bring the app up again. A change to app/schema.sql deserves a dump first.

  • Tokens: one per agent, so the live view and the access log show who did what, and a leaked token can be rotated alone (mint_token.py <agent-id> again).

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md. Security reports go through SECURITY.md.

Credits

Created by @GodrezJr2, who designed it and directs its development. Most of the code was written with Claude Code and checked against daily use.

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Provides persistent memory for AI coding agents via MCP, enabling agents to store and semantically recall facts, events, and lessons across sessions, all running locally without cloud dependencies.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to maintain a private, local-first persistent memory by automatically saving, searching, and retrieving structured project memories through MCP, with hybrid keyword and embedding search, feedback-driven ranking, and no cloud dependency.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents and assistants to share a local-first, token-efficient persistent memory layer across MCP-compatible runtimes, storing typed project facts, decisions, failures, and solutions with temporal validity. It supports offline use and Postgres-compatible storage, so agents can retrieve relevant context without re-embedding entire repositories.
      Apache 2.0
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to store, search, and recall persistent project and cross-project memories locally over MCP, keeping architectural decisions, conventions, and error patterns available across sessions. Also optionally exposes a task server for autonomous task execution driven by that same memory store.
      -