Skip to main content
Glama
mem-universe

mem-universe

by H1an1

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.


Related MCP server: Engram

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

Available Tools

8 tools
deleteC

Delete a memory file. Git keeps history, so it's recoverable. Returns {ok, deleted}.

Inputs: path (required), author_agent (required), reason.

get_skillA

Fetch a whole skill package as {name, files: {relpath: content}}. To install it, write each file into your local skills dir (e.g. ~/.claude/skills//). Any agent can fetch + run a package; Claude-family agents additionally get native auto-invocation.

Inputs: name (required).

listC

List entries under a layer (optionally a prefix within it).

Inputs: layer (required), prefix. Returns: result

list_skillsA

List stored skill packages as [{name, description}] (description from each SKILL.md).

Inputs: no named parameters. Returns: result

put_skillA

Store a runnable skill PACKAGE (a SKILL.md + its scripts/templates) byte-exact under shared/skills//. files maps package-relative paths to text content and MUST include a SKILL.md. Files are stored verbatim — no frontmatter, no template check (unlike write, which is for single markdown notes). The SKILL.md is indexed so search finds the package; any agent can later get_skill to install it. Returns {name, paths, commit}.

To push your local package: read every file under your skills dir (e.g.
~/.claude/skills/<name>/) into `files`, then call this. Text files only (v1).

Inputs: name (required), files (required), author_agent (required), reason.

readB

Read a single memory file by store-relative path.

Inputs: path (required).

writeA

Write a memory file (also indexes it). Returns {ok, path}.

There are exactly two layers. `path` is store-relative and starts with one:
  - `shared/...`    — the cross-agent knowledge base (skills/tools/lessons/rules)
  - `personal/...`  — the owner's personal space (free-form)

`layer` is OPTIONAL — leave it out and it's inferred from the path. If you do
pass it, the only valid keys are "shared" and "personal".

Layers are SHARED spaces, not per-author: every connected agent reads and
writes the same paths. `author_agent` only records who wrote an entry
(provenance); it does not partition or hide anything. So `personal/` is "the
owner's personal layer", visible to all connected agents — NOT "this agent's
private space". Truly secret material should not be put in this store at all.

`type` is one of skill|tool|lesson|rule|conversation|note (inferred from the
path if omitted). An explicit type="skill" must include the 5 template
sections, each headed in Chinese OR English: 目标/Goal, 何时用/When to use,
前置/Preconditions, 步骤/Steps, 验证/Verify.

Inputs: path (required), content (required), author_agent (required), tags, +4 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool serves a distinct purpose: file operations (delete, read, write), skill management (get_skill, put_skill, list_skills), and discovery (list, search). No two tools have overlapping functionality.

    Naming Consistency4/5

    Names are lowercase with underscores for multi-word tools (e.g., get_skill), but single-word names like delete and read break the pattern slightly. Still, the naming is predictable and readable.

    Tool Count5/5

    8 tools cover core operations for memory files and skills without bloat. The set is well-scoped for the stated purpose.

    Completeness4/5

    Covers create/read/delete for files and CRUD for skills except delete_skill. Write presumably overwrites, acting as update. Minor gap: no dedicated skill deletion tool.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A self-hosted MCP server that gives AI agents shared, long-term memory over a git-backed folder of markdown, enabling persistent knowledge search, read, and write without a database.
      16
      24 npm
      21
      MIT
    • A
      license
      B
      quality
      A
      maintenance
      A local MCP server that provides agents with tools to list, read, search, inspect history and diffs, and capture unstructured text in a user-owned Git repository of durable memory.
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server providing persistent, local-first memory for AI agents via Markdown files in a git repo, with search, branching, and auditability.
      5 npm
      2
      MIT