Overview
Persistent memory for AI agents.
Theo Memory gives your agents long-term, scoped, searchable memory backed by
Postgres + pgvector. It exposes a four-verb API — remember · recall · forget
· reflect — across three tiers (user / session / agent), with hybrid
retrieval (semantic + BM25 + entity boost) and bi-temporal queries. It runs on
your Postgres and your LLM key (Apache-2.0), and is consumable as an SDK,
a REST API, an MCP server, or a CLI.
Published on npm as @usetheo/memory (0.2.0, pre-release). Feature-complete
for the core use case; the production-ready bar stays gated on sustained usage
evidence.
Install
npm install @usetheo/memoryRequires Node ≥ 20 and a Postgres with pgvector. Ships two binaries —
themory (REST server + CLI) and themory-mcp (MCP server).
Quick start
import { createLocalMemory } from '@usetheo/memory';
const memory = await createLocalMemory({ vectorStore, embedder, llm });
// Your agent remembers
await memory.user('alice').remember('Prefers dark mode. Speaks Portuguese.');
// Your agent recalls
const facts = await memory.user('alice').recall('UI preferences');
// → [{ text: 'Prefers dark mode', score: 0.94 }]
// Consolidate episodic → semantic
await memory.user('alice').reflect();Run it as a service instead:
export THEOMEM_PG_URI=postgresql://themem:themem@localhost:5432/themem
npm run db:push # apply schema
npx themory server # REST API on :8080 (POST /v1/remember, /v1/recall, …)Core concepts
Three-tier scope
`memory.user(id)`, `memory.session(id)`, `memory.agent(id)` return a scoped store; `memory.skills(repoId)` is a code-as-skill library.
Four-verb API
`remember` · `recall` · `forget` · `reflect`, consistent across every tier — `reflect` consolidates episodic memories into semantic ones.
Hybrid retrieval
Semantic (cosine ANN) + BM25 lexical + entity boost, with threshold gating and optional MMR diversification (`recall({ diversify })`).
Bi-temporal queries
`recall({ asOf })` returns point-in-time snapshots; `episodes()` honors `asOf` for replay.
Multi-tenancy + RBAC
`memory.withWorkspace(id)` scopes every query by tenant (cross-tenant access is a 404, never 403); roles owner / admin / member with last-owner guards.
Pluggable embedders + MCP
`THEOMEM_EMBEDDER=local` (on-device MiniLM) or `openai`; plus a 4-tool MCP server with an OpenMemory-compatible drop-in mode.