Three explicit memory layers. One idempotent API. Self-hosted.
git clone https://github.com/mcgrapeng/thinkback.git && cd thinkback && make dev→ API on :7002 · Admin console on :7001 (both shift to the next free port if taken; in Docker and Kubernetes the API listens on :8000)
English · 中文 · Docs · Changelog · Roadmap · Report a bug · Request a feature
| Chapter | What's in it | Read | |
|---|---|---|---|
| 01 | Thinkback in 60 seconds | What it is, what you get | 30s |
| 02 | Why this exists | The gap between Mem0 and a memory service | 1 min |
| 03 | How it works | L1 / L2 / L3, request flow, architecture | 2 min |
| 04 | Quickstart | Run it, write a round, recall it | 2 min |
| 05 | The admin console | Visual tour of all 7 pages | 1 min |
| 06 | Operating it | Performance, config, layout, extending | 3 min |
| 07 | Reference | Endpoints, FAQ, where to go next | as needed |
Most AI apps work in the first conversation and fail in the tenth — the assistant forgot the user's preferences, the issue from yesterday, the tool call you spent three turns debugging. Persistent memory isn't optional at that point.
Thinkback is that memory layer, as a service you run yourself. It keeps three kinds of memory in explicit, separate layers, exposes them through one HTTP/gRPC API, and tells you plainly when something is broken.
Built on Mem0 as the long-term engine, plus PostgreSQL and Milvus.
|
🧠 Three layers that don't fight Short-term context, running session summaries, and long-term facts — each with strict ownership. No cross-writes, no surprise overwrites. |
✅ Idempotent by default
|
|
🚨 Honest failure When the LLM or vector store is down, responses come back |
🔌 HTTP + gRPC, one schema Pydantic models are the single source of truth. Pick your protocol, share your types, stay typed
end to end under |
|
🎛️ Admin you can actually use React 19 console: inspect every memory, replay every task, revoke or supersede on demand, with a ⌘K command palette and full keyboard navigation. |
🛠️ Yours to run Postgres + Milvus + Mem0, all open source. Kubernetes-native with liveness/readiness probes and Prometheus metrics. Apache 2.0. |
| Area | What you get |
|---|---|
| Memory model | Three layers (L1/L2/L3) with bitemporal validity — valid_at / invalid_at. Superseding a fact keeps history instead of overwriting it |
| Lifecycle | Index state machine: ACTIVE / DELETED / SUPERSEDED / SUPPRESSED, decoupled from backend storage state |
| Reliability | Task state machine with optimistic locking, retry budgets, dead-lettering, and orphan-task reclaim on cold start |
| Governance | Scoped delete (MEMORY / SESSION / ALL) with tombstones, plus a full audit trail |
| Integration | One HTTP/gRPC surface on an internal network — no API key, per-client-IP rate limit, Idempotency-Key replay safety |
| Type profiles | Per-namespace profiles in profiles/ decide which memory types are admitted, how long they live, and which ones expire |
| Operations | K8s manifests, Helm chart, Alembic migrations, Prometheus metrics, deterministic test suite |
v1.0 is out. See the changelog for the full release notes.
We shipped a multi-tenant support agent once. We rewrote its "memory layer" three times — once in Postgres, once in Redis, once as a Sidekiq cron job — before realising the memory layer wasn't our product. It was a tax on the product.
Mem0 is an excellent memory engine. It gives you fact extraction and semantic recall. What it does not give you is a service — and wiring it into a production app means you now own all of this:
| You'd have to build yourself | What Thinkback provides |
|---|---|
| Session-level context (last-N rounds, running summary) | L1 journal + L2 debounced summaries in PostgreSQL |
| Exactly-once writes across retries and replays | Fingerprint-based idempotent append |
| Behaviour when the LLM / embedding / vector store is down | Explicit degraded=true + reasons — never a half-answer |
| Background extraction with backpressure | Async L3 queue with capacity limits, drain, orphan-task reclaim |
| An API to list / edit / delete long-term memories | Full management surface with scoped deletes and audit |
| Observability of what the memory layer actually did | Task state machine, retry counts, last error, admin dashboard |
| Safe, scoped deletion | MEMORY / SESSION / ALL scopes with tombstones |
| Schema and readiness for deployment | Alembic migrations, liveness/readiness probes, metrics |
| Raw Mem0 | LangChain memory | DIY Postgres + pgvector | Thinkback | |
|---|---|---|---|---|
| Idempotent writes across retries | ❌ | ✅ | ||
| Background extraction w/ backpressure | ❌ | ❌ | ❌ | ✅ |
Explicit degraded when LLM is down |
❌ | ❌ | ❌ | ✅ |
| Three-layer separation | ❌ | ❌ | ❌ | ✅ |
| Task state machine + dead-lettering | ❌ | ❌ | ❌ | ✅ |
| Bitemporal validity | ❌ | ❌ | ✅ | |
| Admin console (governance) | ❌ | ❌ | ❌ | ✅ |
| HTTP + gRPC, shared schema | ❌ Python only | ❌ Python only | ✅ | |
| Bring-your-own LLM / embedding | ✅ | ✅ | ✅ | ✅ |
| Production deployable | ❌ | ❌ | ✅ |
If your use case is "one process, one user, no retries" — call Mem0 directly. If you're shipping a service other teams depend on, this is the gap Thinkback fills.
Layers never cross-write. Each one owns its data outright.
|
L1 — Round journal Each complete Backed by PostgreSQL |
L2 — Session summary Running context for the session. Backed by PostgreSQL + LLM |
L3 — Long-term memory Cross-session facts and preferences. Backed by Mem0 + Milvus |
flowchart LR
L1["L1 · Round journal<br/>PostgreSQL"]
L2["L2 · Session summary<br/>PostgreSQL + LLM"]
L3["L3 · Long-term memory<br/>Mem0 + Milvus"]
L1 -->|append| L2
L2 -->|extract| L3
L3 -.->|recall| L1
appendwrites the round to L1 synchronously and returns. L2 is scheduled; L3 extraction is queued in the background.recallreads all three layers and merges hits, tagging each with its layer so the caller knows where a fact came from.- A background worker drains the L3 queue: extract facts via Mem0, embed and store in Milvus. Bounded retries, then dead-letter.
- Anything degraded comes back flagged with the reason. Callers decide whether to fall back or surface an error.
Full internals — hexagonal ports, dependency inversion, the exact schema — in docs/ARCHITECTURE.md.
git clone https://github.com/mcgrapeng/thinkback.git
cd thinkback
uv sync --frozen --group dev # install dependencies
make dev-up # start a local PostgreSQL (or point .env at your own)
cp .env.example .env # fill in MEMORY_LLM_KEY, MILVUS_URL, endpoints
make dev # API on :8000 + admin console on :7001Verify:
curl http://localhost:8000/health/readyPOST /memory/append records one complete user → assistant round, triggers L1/L2 updates, and
queues background L3 extraction.
curl -X POST http://localhost:8000/memory/append \
-H "Content-Type: application/json" \
-d '{
"request_id": "req-001",
"user_id": "alice",
"session_id": "support-001",
"round_id": "round-001",
"source_timestamp": "2026-01-15T10:00:00Z",
"messages": [
{ "message_id": "m1", "role": "user",
"content": "I prefer dark mode and vim keybindings.",
"timestamp": "2026-01-15T10:00:00Z" },
{ "message_id": "m2", "role": "assistant",
"content": "Noted. I will remember that.",
"timestamp": "2026-01-15T10:00:02Z" }
]
}'{
"status": "completed",
"task_id": "task-abc123",
"round_id": "round-001",
"l3_events": []
}POST /memory/recall returns L1/L2/L3 hits, with an explicit degradation signal when a layer is
unavailable.
curl -X POST http://localhost:8000/memory/recall \
-H "Content-Type: application/json" \
-d '{
"user_id": "alice",
"session_id": "support-002",
"query": "What UI preferences does this user have?",
"l3_limit": 3
}'{
"status": "ok",
"degraded": false,
"degradation_reasons": [],
"items": [
{ "layer": "L3", "content": "Prefers dark mode and vim keybindings." }
]
}Thinkback is deployed on an internal network, and the business API needs no credentials —
the network is the trust boundary. Send Idempotency-Key on writes for replay safety and
X-Trace-Id if you want to correlate your logs with the service logs.
curl -X POST http://your-thinkback:8000/memory/recall \
-H "Content-Type: application/json" \
-H "X-Trace-Id: trace-001" \
-d '{ "user_id": "u_8421", "session_id": "s_001", "query": "用户偏好什么编辑器?", "l3_limit": 5 }'Python, TypeScript, and cURL walkthroughs: docs/SDK.md. Full HTTP surface: docs/API.md. The v1 public integration protocol (API key + scope + tenant) was removed — the spec is kept as a historical record.
React 19 + Vite + TanStack Router. Seven pages, a ⌘K command palette, j/k/x keyboard
navigation, URL deep links, and a responsive layout.
Four hero KPIs, system pulse, L3 queue status, and recent audit activity.
Filter by user and status, jump from a memory back to the round that produced it, compare revisions.
KPI sparklines, the full task state machine, retry counts, last error, and dead-letter inspection.
Delete by memory, session, or user. Always scoped, always confirmed, always audited.
Every delete, update, and rebuild, filterable, with operator and timestamp.
A curated, read-only view of runtime configuration.
This page still documents the v1 public integration protocol — API keys, scopes, and
/v1/memory/*. That surface was removed from the service: the business API is now
/memory/* on an internal network, with no API key. The current contract lives in
docs/API.md.
More screenshots
Memories — detail view
Tasks — expanded row
Governance — update a memory
Mobile-responsive layout
Single-node dev profile — make dev, M3 MacBook Air, mock LLM.
| Workload | p50 | p95 | Throughput |
|---|---|---|---|
POST /memory/append (small round) |
8 ms | 22 ms | 850 req/s |
POST /memory/recall (5 hits) |
24 ms | 68 ms | 410 req/s |
GET /memory/items (50 results) |
4 ms | 9 ms | 2 200 req/s |
POST /memory/delete (scoped) |
6 ms | 14 ms | 1 100 req/s |
L3 extraction runs asynchronously — end-to-end latency is dominated by your configured LLM and embedding endpoints, not by Thinkback itself.
All runtime config comes from environment variables. The full list — every knob, with
comments — lives in .env.example; copy it to .env and fill in the
values you need. See docs/CONFIGURATION.md for how config
and credentials are managed (and why a typo'd variable name fails silently).
| Variable | Purpose | Default |
|---|---|---|
MEMORY_LLM_KEY |
LLM API key for L2 / L3 | — |
MEMORY_LLM_BASE_URL |
OpenAI-compatible endpoint | — |
MEMORY_LLM_MODEL |
LLM model name | qwen-plus-latest |
MEMORY_EMBEDDING_API_KEY |
Embedding model API key | — |
MEMORY_EMBEDDING_BASE_URL |
OpenAI-compatible embedding endpoint | — |
MEMORY_EMBEDDING_MODEL |
Embedding model | default-embedding |
MEMORY_EMBEDDING_DIMS |
Embedding vector dimensions | 1024 |
DATABASE_URL |
PostgreSQL connection URL | — |
MILVUS_URL |
Milvus server URL | http://localhost:19530 |
MILVUS_DATABASE |
Milvus database name | default |
MEMORY_L3_WRITE_MODE |
async (default) or sync |
async |
MEMORY_DECAY_ENABLED |
Enable the decay sweeper | false |
MEMORY_DECAY_MIN_AGE_DAYS |
Suppression threshold (days) | 90 |
GRPC_ENABLED |
Start gRPC alongside HTTP | true |
Decay is off by default. When enabled, aged and rarely-recalled long-tail memories are suppressed — unreachable, never deleted. Recalling one strengthens it back.
thinkback/
├── src/thinkback/
│ ├── api/ FastAPI routers — memory core, health probes,
│ │ rate limit, idempotency, standardised errors, admin
│ ├── domain/ Pure business logic — entities, enums, ports, errors
│ ├── memory/ Orchestration — MemoryService, L3 backends,
│ │ L1+L2 repositories, Pydantic schemas
│ ├── infra/ PostgreSQL / Milvus / logging / config
│ └── rpc/ gRPC server and proto mapping
├── web/ Admin console (React 19 + Vite + TanStack Router)
├── proto/memory.proto gRPC contract
├── alembic/ Database migrations
├── tests/ pytest suite (870+ tests)
└── docs/ Design docs and runbooks
- Swap the L3 backend — implement the
MemoryBackendport inthinkback.domain.portsand register it inthinkback.memory.backends. Mem0 is the default; Qdrant-native or pgvector adapters are straightforward. - Add an admin page — drop a file in
web/src/pages/, register the route inweb/src/main.tsx, add a sidebar entry inweb/src/components/layout.tsx. - Change extraction rules — edit
THINKBACK_CUSTOM_INSTRUCTIONSinsrc/thinkback/memory/backends/mem0_library.py, or the type profile inprofiles/(admission, retention, TTL). The console does not edit prompts.
make dev # API + admin console
make test # backend suite
make test-fast # only tests affected by your changes (testmon)
make coverage # suite + coverage report (observation only, non-blocking)
make check # format-check + lint + typecheck + mutation-audit + eval (what CI runs)
make test-ui # frontend component tests
make test-e2e # Playwright end-to-end + axe a11y scanCode style: ruff (lint + format), mypy --strict for Python; strict TypeScript, no any at
boundaries.
26 endpoints across three groups, plus a / root probe. Swagger UI at /docs, ReDoc at /redoc.
The gRPC service in proto/memory.proto mirrors the same operations.
The MCP server (thinkback-mcp) projects them onto MCP tools for assistants that speak MCP — see docs/MCP.md.
Memory core — /memory/* (no auth; internal network)
| Method | Path | Purpose |
|---|---|---|
POST |
/memory/append |
Write a round; triggers L1/L2/L3 |
POST |
/memory/recall |
Recall memories with a degradation signal |
POST |
/memory/delete |
Scoped delete (MEMORY / SESSION / ALL), tombstone kept |
POST |
/memory/suppress |
Take out of recall, keep text and tombstone |
POST |
/memory/erase |
Physically erase the text |
GET |
/memory/items |
List long-term memories of a user |
GET |
/memory/items/{memory_id} |
One memory |
POST |
/memory/update |
Update text; history preserved |
GET |
/memory/tasks/{task_id} |
Task state: retries, last error, result |
GET |
/memory/l3/background-status |
L3 queue and worker status |
Health — /health/*
| Method | Path | Purpose |
|---|---|---|
GET |
/health |
Process health (version, environment) |
GET |
/health/live |
Liveness probe |
GET |
/health/ready |
Readiness probe (PostgreSQL / Milvus / Mem0) |
GET |
/health/metrics |
Prometheus metrics |
Admin — /admin/api/* (no auth; internal network only)
| Method | Path | Purpose |
|---|---|---|
GET |
/admin/api/overview |
KPIs, system pulse, L3 status, recent audit |
GET |
/admin/api/tasks |
Task list with status filter |
GET |
/admin/api/memories |
Memory list with source back-link |
GET |
/admin/api/memories/{memory_id}/source |
Source back-link of one memory |
GET |
/admin/api/audit |
Audit log, filterable by action |
POST |
/admin/api/{delete,update,rebuild} |
Governance actions, idempotent |
GET |
/admin/api/health/detail |
Dependency detail |
GET |
/admin/api/config |
Runtime config |
POST |
/admin/api/maintenance/reclaim-orphan-tasks |
Reclaim orphaned background tasks |
Full reference with request/response bodies: docs/API.md.
How is this different from calling the Mem0 SDK directly?
Mem0 is an excellent memory engine — it gives you fact extraction and semantic recall. It does not give you a service. Thinkback wraps it with session-level context, idempotent writes, explicit degradation signals, background task governance, scoped deletes with tombstones, an admin dashboard, and HTTP + gRPC access. If you need "one process, one user, no retries", call Mem0 directly.
Can I use my existing Mem0 + Milvus setup?
Yes. Point MEMORY_LLM_*, MEMORY_EMBEDDING_*, MILVUS_URL, and MILVUS_DATABASE at your
existing infrastructure. No schema migration — Thinkback uses the same collection.
What happens when the LLM or vector store goes down?
Thinkback never returns a half-answer. The response is marked degraded=true with
degradation_reasons naming which layer is down and why. Callers decide whether to fall back or
surface an error.
Is it production-ready?
Hexagonal ports, Pydantic v2 with mypy --strict, Alembic migrations, Kubernetes liveness/readiness
probes, Prometheus metrics, and 870+ tests. The admin console is a React 19 SPA with keyboard
navigation, accessibility, and responsive layout.
How does it scale?
L3 extraction is async by default — scale it with MEMORY_L3_EXECUTOR_WORKERS and
MEMORY_L3_MAX_PENDING_TASKS. Memory is isolated per namespace (the scope tag on every
request), not per tenant: there is no tenant dimension in the API. See the
operations runbook for tuning and recovery.
Can I customize memory extraction?
Yes, in code — the console does not edit prompts. Extraction constraints live in
THINKBACK_CUSTOM_INSTRUCTIONS (src/thinkback/memory/backends/mem0_library.py), and the
memory types (admission, retention, TTL, conflict handling) live in the namespace profile
under profiles/.
|
Architecture deep-dive API reference SDK examples |
Deployment guide Operations runbook Configuration & credentials Integration protocol v1 |
A living document — docs/ROADMAP.md. Vote on issues and we'll prioritise.
Good first issues: open issues labelled
good first issue.
PRs welcome for bug fixes, new backends, console improvements, and docs.
Apache 2.0. Use it, modify it, ship it commercially — keep the copyright notice and disclaimer.
Built on Mem0 (the long-term engine), Milvus (vector store for L3), PostgreSQL (durable substrate for L1/L2), FastAPI, TanStack (console), Pydantic, and the open-source AI memory community.





