mem-universe

A self-hosted MCP memory server that gives a personal multi-agent fleet (Claude Code, ChatGPT, Codex, Cursor, and any other MCP client) one shared, git-backed memory. Agents install nothing. They connect over MCP and search / read / write.

The problem it solves: "Claude on one machine figured out how to do X, but Codex on another machine has no idea." One memory, every agent, instantly.

---

The idea

Most "give your agent memory" setups sync skill files into each tool, in each tool's own format. That does not scale across a fleet: every new agent needs a converter, and knowledge learned in one place is invisible everywhere else.

mem-universe flips it: keep one plain-text store, and let every agent read and write it at use time over MCP. A skill is just markdown any agent can follow, so there is nothing to convert. Learn something once, and the whole fleet can recall it on the next task.

---

Architecture

flowchart LR
  subgraph agents [Your agent fleet]
    A1[Claude Code]
    A2[ChatGPT]
    A3[Codex / Cursor]
    A4[Other MCP clients]
  end

  A1 -- "Bearer token" --> S
  A3 -- "Bearer token" --> S
  A4 -- "Bearer token" --> S
  A2 -- "token in URL path" --> S

  subgraph server [mem-universe server  ·  FastMCP over HTTP]
    S[auth + path validation]
    S --> T["tools: search / read / write / list / delete<br/>put_skill / get_skill / list_skills"]
    T --> IDX[("BM25 index<br/>local, rebuildable")]
    T --> ST[git working copy]
  end

  ST -- "commit, then async push" --> GH[("private store repo<br/>on GitHub")]
  ST --> L1["shared/  ·  skills, lessons, rules"]
  ST --> L2["personal/  ·  owner profile, notes"]

Key design decisions

1. MCP is the integration layer, not file-syncing. Knowledge is stored once as plain text and retrieved on demand. Add one entry and the whole fleet sees it, with no per-agent format conversion.

2. Git is the database. The store is a git repo of markdown files. Every write is a commit, then an async push to GitHub. You get version history, recoverable deletes (delete is also a commit), human-readable data, and "backup" for free. Writes are serialized by a single-writer lock; reads come from the local clone, so they never wait on the network. Last write wins, so there are no merge conflicts by design.

3. Code and data live in two separate repos. This server (code) is one repo. Your memory (data) is a separate, private store repo that the server clones and writes to. That split is why this codebase can be public while your memory stays private. Never put the store in this repo.

4. Two layers, one permission. shared/ is cross-agent knowledge (skills, lessons, rules). personal/ is the owner's own content. Any valid token can read and write everything: tokens gate who connects, not which layer. For a single owner's fleet on a private network, scoped permissions are over-engineering. Anything truly secret should not go in the store at all.

5. Retrieval, not installation. Agents install nothing. To make an agent use the library, drop a one-line "recall first" marker into its existing instruction file (CLAUDE.md, AGENTS.md, ...) telling it to search before acting. Multi-file, runnable skills travel as packages (put_skill / get_skill).

6. Two ways to authenticate, so Claude and ChatGPT both connect. Clients that can send headers use Authorization: Bearer <token>. Clients that cannot set custom headers (such as a ChatGPT connector) put the token in the URL path: https://<host>/<token>/mcp. Same server, both worlds.

7. Hand-rolled, bilingual BM25 search. No external embedding service. It is light, works offline, and tokenizes mixed CJK + English. The index lives locally and is never committed (it rebuilds from the store).

---

The tools

Tool	What it does
search	BM25 search across the store; returns ranked {path, score, snippet, type}
read	Read one entry by store-relative path
write	Write an entry (also indexes it); layer inferred from the path
list	List entries under a layer / prefix
delete	Delete an entry (git keeps history, so it is recoverable)
put_skill	Store a multi-file skill package under shared/skills/<name>/
get_skill	Fetch a skill package to install locally
list_skills	List available skill packages

Layers

<store>/
├── shared/      # cross-agent knowledge: skills / tools / lessons / rules
└── personal/    # the owner's own content: profile, notes, imports

A write path starts with the layer name (shared/... or personal/...); the layer argument is optional and inferred from the path.

What happens on one write

write(path, content)
  -> validate path (must stay in-layer; reject ../ and cross-layer symlinks)
  -> acquire single-writer lock
  -> write file + stamp frontmatter
  -> git commit
  -> return ok
  -> (background) async push to the private store repo
  -> update the local BM25 index

Reads and searches always hit the local clone, so they do not block on git.

---

Deploy

Full steps are in DEPLOY.md. The short version (Docker):

git clone https://github.com/H1an1/mem-universe && cd mem-universe/deploy
cp mem.env.example mem.env     # set MEMORY_TOKEN and MEM_STORE_REMOTE (your private store repo)
# edit Caddyfile: point your domain at this VPS
docker compose up -d --build

This runs the server behind Caddy (automatic TLS). Agents reach it at https://<your-domain>/mcp. Generate a token with openssl rand -hex 32. A Tailscale-only (no public exposure) compose file is also included.

Connect your agents

All clients need the URL plus a token.

Claude Code

claude mcp add --transport http mem-universe https://<your-domain>/mcp \
  --header "Authorization: Bearer <YOUR_TOKEN>"

Claude Desktop / claude.ai (custom connector): add an HTTP MCP server with URL https://<your-domain>/mcp. If the client supports a header, use Authorization: Bearer <YOUR_TOKEN>; otherwise use the path-token URL below.

ChatGPT (custom connector): ChatGPT connectors cannot set custom headers, so put the token in the path:

https://<your-domain>/<YOUR_TOKEN>/mcp

Cursor / Codex / others: add an HTTP MCP server with the same URL and an Authorization: Bearer <YOUR_TOKEN> header (see your client's MCP docs).

Every agent uses the same token. To make agents actually recall before acting, add a short "recall first" marker to each agent's instruction file.

---

Security model

• One token unlocks every layer; tokens gate connection, not content. A read-only token variant exists for untrusted external readers.
• The server rejects path traversal (../) and cross-layer symlinks at the filesystem level, independent of auth.
• Run it on a private network (such as Tailscale) or behind TLS with a strong token. Anything that truly must never be read by any agent does not belong in the store.
• Secrets live only in deploy/mem.env (gitignored). Never commit them.

How it was built

Built with a maker/checker loop: each feature was written, then reviewed by a separate pass plus an adversarial verifier whose job was to break it. That caught real bugs before release, including a cross-layer symlink that let a read-scoped token reach another layer, and an rmtree that followed symlinks. The suite has 100+ tests and is linted clean.

Develop

uv sync           # create venv (Python 3.12) + install deps
uv run pytest     # tests
uv run ruff check .
uv run mem-server # run the MCP server over stdio

License

MIT