How do I use umo-memory?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@umo-memory Remember that I prefer dark mode in all my projects." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

umo-memory

by UmoLab

Overview Schema Related Servers Score Discussions

Python

Local

umo-memory

Persistent memory for AI coding agents. Local-first. Zero cloud. Plug-and-play with Claude Code via MCP.

Tests Coverage Python License MCP

Stop losing context between sessions. umo-memory gives your AI agent a long-term brain that runs entirely on your laptop. Stored facts (preferences, decisions, conventions) survive across sessions and are recalled by semantic similarity — so the next time you ask Claude to "use my dark theme," it remembers without you re-explaining.

Built for Claude Code but works with any MCP-compatible client.

Why

Every Claude Code session starts cold. You re-explain your preferences, your project's conventions, your architecture decisions. After 50 sessions, you've typed the same context thousands of times.

umo-memory solves this with persistent memory:

Stored automatically by your agent via MCP tools (store, recall, etc.)
Recalled by semantic similarity (vector search, no exact-key matching)
Survives sessions, restarts, machines (single SQLite file)
100% local — no API calls, no telemetry, no cloud lock-in
Battle-tested — 179 tests, 92% coverage (with branch tracking), real concurrency tests

Related MCP server: Tages

30-second quickstart

1. Install

pip install umo-memory

(First run downloads a ~80MB embedding model — one-time, then cached.)

2. Initialize the database

umo init

Creates ~/.local/share/umo-memory/memory.db.

3. Wire into Claude Code

Add to ~/.claude/mcp_servers.json (or .mcp.json in your project):

{
  "mcpServers": {
    "memory": {
      "command": "umo",
      "args": ["start"],
      "env": {"UMO_PATH": "~/.local/share/umo-memory/memory.db"}
    }
  }
}

4. Use it

Open Claude Code. It now has access to:

store — save a fact (preference, decision, convention)
recall — semantic search across stored facts
update / forget — mutate stored facts
recent / browse — inspect what's stored

Tell Claude: "Remember that I prefer dark mode in all my projects." Next session, it'll know.

First day with umo

A 5-minute walkthrough to prove the round-trip works:

$ umo init
Initialized umo-memory at ~/.local/share/umo-memory/memory.db

$ umo list
No memories yet. Run `umo init` then store something.

# Stash something via Python (or via Claude Code)
$ python -c "from umo import Memory; \
  m = Memory(); \
  m.store('I prefer dark mode in editors', 'fact', 0.8, subject_key='user.theme')"

$ umo list
  01KVF2CKW772  fact    imp=0.80  [user.theme] I prefer dark mode in editors

$ umo search "what theme does the user like"
  1. 01KVF2CKW772  fact    imp=0.80  [user.theme] I prefer dark mode in editors

$ umo show 01KVF2CKW772
Memory 01KVF2CKW772QQG4ZRPSDEH99E
  kind:         fact
  subject_key:  user.theme
  importance:   0.80
  source:       manual
  ...

  content:
    I prefer dark mode in editors

If you see this — Claude Code will too. The next session, just open Claude and ask "what theme does the user like?" — it'll know.

What's stored

Three kinds of memories:

Kind	Use for	Example
`fact`	User preferences, project facts, conventions	"User prefers dark mode"
`event`	Things that happened, dated context	"Migrated from Postgres to SQLite on 2026-01-15"
`lesson`	Procedural rules the agent should follow	"When using sqlite-vec, always include `AND k = ?`"

Each memory can have a subject_key (e.g. user.theme, project.db_choice) for deterministic lookup, plus metadata and importance (0.0–1.0).

Architecture

┌──────────────────────────────────────────────────┐
│  Claude Code (or any MCP client)                 │
│         │                                        │
│         │ MCP protocol (JSON-RPC over stdio)     │
│         ▼                                        │
│  ┌──────────────────────────────────────────┐    │
│  │  umo_memory mcp_server                      │    │
│  │  (9 tools: store, recall, update, …)      │    │
│  └──────────────┬───────────────────────────┘    │
│                 │                                │
│                 ▼                                │
│  ┌──────────────────────────────────────────┐    │
│  │  umo_memory core (Python)                   │    │
│  │  ┌──────────┐ ┌──────────┐ ┌─────────┐    │    │
│  │  │  Store   │ │ Recall   │ │ Embedder│    │    │
│  │  │ (SQLite) │ │(vec+fts) │ │  (sbert)│    │    │
│  │  └──────────┘ └──────────┘ └─────────┘    │    │
│  └──────────────┬───────────────────────────┘    │
│                 │                                │
│                 ▼                                │
│       SQLite + FTS5 + vec0  (~/.local/share/…)   │
└──────────────────────────────────────────────────┘

Everything in one SQLite file. SQLite gives ACID transactions, WAL for concurrent reads, and single-file backup. No Docker, no Postgres, no Redis.

Comparison

	umo-memory	mem0	LangChain Memory	custom RAG
Local-first	✅ single file	❌ cloud default	❌ external DB	depends
MCP integration	✅ built-in	❌ DIY	❌ DIY	❌ DIY
No external services	✅	❌	❌	depends
Vector search built-in	✅ sqlite-vec	✅	depends	depends
FTS5 keyword fallback	✅	❌	❌	❌
Subject-key dedup	✅	✅	❌	❌
Setup time	30 sec	5 min	30 min	hours
Dependency footprint	7 packages	heavy	very heavy	DIY

When to use umo-memory: you want persistent memory that just works, runs on your laptop, doesn't phone home, and integrates with Claude Code in under a minute.

When NOT to use it: you need multi-tenant cloud storage, embeddings for non-text modalities, or 100k+ memories per user (vector search in SQLite caps out around there).

Backing up and restoring

Everything is in one SQLite file. To back up:

cp ~/.local/share/umo-memory/memory.db backup.db
# Or export to portable JSONL:
umo export ~/.local/share/umo-memory/memory.db > backup.jsonl

To restore:

# From a SQLite file:
cp backup.db ~/.local/share/umo-memory/memory.db
# From a JSONL file:
umo init ~/.local/share/umo-memory/memory.db --force
umo import_data ~/.local/share/umo-memory/memory.db backup.jsonl

Upgrading the embedding model

If you switch UMO_EMBEDDING_MODEL or upgrade sentence-transformers, old memories have embeddings in the old dimension. Run:

umo reembed

This re-encodes every memory using the current model. Without it, sqlite-vec queries on mixed-dim embeddings will crash.

Usage

CLI

umo init                              # create empty DB
umo verify                            # health check (8 checks)
umo stats                             # show counts, model, schema version
umo list                              # show recent memories (formatted)
umo show <id>                         # show one memory by id
umo search "query"                    # semantic search via CLI
umo start                             # run MCP server on stdio
umo export <path> > backup.jsonl      # export all memories to JSONL
umo import_data <path> <file.jsonl>   # import from JSONL backup
umo import <path> <pm-db-path>        # import from PMB-format DB
umo reembed                           # re-encode stale embeddings

Python API

from umo import Memory

mem = Memory(path="~/.local/share/umo-memory/memory.db")

# Store a fact (with subject_key for deterministic dedup)
mem.store(
    content="User prefers dark mode",
    kind="fact",
    importance=0.8,
    subject_key="user.theme",
)

# Semantic recall (results are MemoryRecord, sorted by relevance)
results = mem.recall("what theme does the user prefer?")
for r in results:
    print(f"[{r.kind}]  {r.content}")

# Update
mem.update(id=results[0].id, content="User prefers dark mode in editors, light in terminals")

# Forget
mem.forget(id=results[0].id)

# Browse by prefix
for item in mem.browse(subject_key_prefix="user."):
    print(item.content)

MCP tools

When running as an MCP server, these tools are exposed:

Tool	Purpose
`store`	Store a fact/event/lesson
`recall`	Semantic search across all memories
`update`	Update content/importance/metadata
`forget`	Soft-delete (archive)
`recent`	Browse recent memories
`browse`	List by subject_key prefix
`stats`	Counts, schema version, model info
`store_many`	Atomic batch insert
`recall_many`	Batch semantic search

For migration from PMB-format DBs, use the Python API: from umo_memory.importers.pmb import import_pmb.

Storage format

Single SQLite file with three tables:

memories — content + metadata (subject_key, kind, importance, source, timestamps)
memory_fts — FTS5 virtual table for keyword fallback
memory_vec — sqlite-vec virtual table for semantic search

Schema migrations: schema_version table tracks applied migrations; umo init upgrades existing DBs in place.

Testing

git clone https://github.com/yourname/umo-memory
cd umo-memory
pip install -e ".[dev]"
pytest                     # 179 tests, ~10 min on CPU
pytest --cov=umo_memory       # with coverage
ruff check src tests       # lint

Documentation

License

Apache 2.0. See LICENSE.

Credits

sqlite-vec — vector search in SQLite
sentence-transformers — local embeddings
fastmcp — MCP server framework
python-ulid — sortable IDs

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

1Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/UmoLab/umo-memory'

If you have feedback or need assistance with the MCP directory API, please join our Discord server