Skip to content
mcgrapengPublic

About

是什么: 面向 Agent 的轻量记忆后端服务 | 能干什么: 存取对话按需检索与回放 | 解决: Agent 每轮会话结束即失忆 | 何时选: 要给自建 Agent 接长期记忆时

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

269 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Thinkback — Self-hosted memory service for AI conversations

Release v1.0 Latest commit License: Apache 2.0 Python 3.12+ CI passing

FastAPI ruff mypy strict

Stars Forks Watchers Awesome Mem0


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

Contents

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

01 · Thinkback in 60 seconds

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

journal_id / request_id fingerprints make every write replay-safe. Send the same round twice, get the same result. No duplicates, no corruption.

🚨 Honest failure

When the LLM or vector store is down, responses come back degraded=true with degradation_reasons. Never a half-answer dressed up as a real one.

🔌 HTTP + gRPC, one schema

Pydantic models are the single source of truth. Pick your protocol, share your types, stay typed end to end under mypy --strict.

🎛️ 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.

Also in the box

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.

02 · Why this exists

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

How it compares

Raw Mem0 LangChain memory DIY Postgres + pgvector Thinkback
Idempotent writes across retries ❌ ⚠️ ⚠️ build it ✅
Background extraction w/ backpressure ❌ ❌ ❌ ✅
Explicit degraded when LLM is down ❌ ❌ ❌ ✅
Three-layer separation ❌ ❌ ❌ ✅
Task state machine + dead-lettering ❌ ❌ ❌ ✅
Bitemporal validity ❌ ❌ ⚠️ build it ✅
Admin console (governance) ❌ ❌ ❌ ✅
HTTP + gRPC, shared schema ❌ Python only ❌ Python only ⚠️ build it ✅
Bring-your-own LLM / embedding ✅ ✅ ✅ ✅
Production deployable ❌ ❌ ⚠️ build it ✅

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.

03 · How it works

Three layers, one direction of flow

Layers never cross-write. Each one owns its data outright.

L1 — Round journal

Each complete user → assistant round.

Backed by PostgreSQL
Refresh Append-only, retain last N rounds

L2 — Session summary

Running context for the session.

Backed by PostgreSQL + LLM
Refresh Debounced — one LLM call per N rounds

L3 — Long-term memory

Cross-session facts and preferences.

Backed by Mem0 + Milvus
Refresh Background extraction, semantic recall

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
Loading

Request flow

  1. append writes the round to L1 synchronously and returns. L2 is scheduled; L3 extraction is queued in the background.
  2. recall reads all three layers and merges hits, tagging each with its layer so the caller knows where a fact came from.
  3. A background worker drains the L3 queue: extract facts via Mem0, embed and store in Milvus. Bounded retries, then dead-letter.
  4. Anything degraded comes back flagged with the reason. Callers decide whether to fall back or surface an error.

Thinkback architecture

Full internals — hexagonal ports, dependency inversion, the exact schema — in docs/ARCHITECTURE.md.

04 · Quickstart

Run the service

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 :7001

Verify:

curl http://localhost:8000/health/ready

Write a memory round

POST /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": []
}

Recall relevant memory

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." }
  ]
}

Integrating a business system

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.

05 · The admin console

React 19 + Vite + TanStack Router. Seven pages, a ⌘K command palette, j/k/x keyboard navigation, URL deep links, and a responsive layout.

Overview — system health at a glance

Overview

Four hero KPIs, system pulse, L3 queue status, and recent audit activity.

Memory browser — search, source back-link, compare

Memory browser

Filter by user and status, jump from a memory back to the round that produced it, compare revisions.

Tasks — state, retries, dead letters

Tasks

KPI sparklines, the full task state machine, retry counts, last error, and dead-letter inspection.

Governance — scoped delete with confirmation

Governance

Delete by memory, session, or user. Always scoped, always confirmed, always audited.

Audit timeline

Audit

Every delete, update, and rebuild, filterable, with operator and timestamp.

System config

Config

A curated, read-only view of runtime configuration.

Integration — protocol notes (retired)

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

Memory detail

Tasks — expanded row

Tasks expanded

Governance — update a memory

Governance update

Mobile-responsive layout

Mobile

06 · Operating it

Performance

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

Latency p50 vs p95

L3 extraction runs asynchronously — end-to-end latency is dominated by your configured LLM and embedding endpoints, not by Thinkback itself.

Configuration

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.

Project layout

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

Extending

  • Swap the L3 backend — implement the MemoryBackend port in thinkback.domain.ports and register it in thinkback.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 in web/src/main.tsx, add a sidebar entry in web/src/components/layout.tsx.
  • Change extraction rules — edit THINKBACK_CUSTOM_INSTRUCTIONS in src/thinkback/memory/backends/mem0_library.py, or the type profile in profiles/ (admission, retention, TTL). The console does not edit prompts.

Development

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 scan

Code style: ruff (lint + format), mypy --strict for Python; strict TypeScript, no any at boundaries.

07 · Reference

API surface

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.

FAQ

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/.

Documentation

Architecture deep-dive
Hexagonal ports, dependency inversion, schema and data flow

API reference
Complete HTTP and gRPC surface with request/response bodies

SDK examples
Python, TypeScript, and cURL client walkthroughs

Deployment guide
Kubernetes manifests, Helm chart, production config

Operations runbook
Debugging, recovery, scaling, incident procedures

Configuration & credentials
Where every environment variable lives, and how secrets stay out of the repo

Integration protocol v1
Historical — the v1 public API was never shipped; see the notes in the spec

Roadmap

Roadmap

A living document — docs/ROADMAP.md. Vote on issues and we'll prioritise.

Community

Discussions Issues Contributing Code of Conduct Security

Good first issues: open issues labelled good first issue. PRs welcome for bug fixes, new backends, console improvements, and docs.

License

Apache 2.0. Use it, modify it, ship it commercially — keep the copyright notice and disclaimer.

Acknowledgments

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.


If Thinkback is useful to you, consider giving it a ⭐ on GitHub — it helps others find it.

Star History

Built for teams who need memory to be a service, not a side project.

About

是什么: 面向 Agent 的轻量记忆后端服务 | 能干什么: 存取对话按需检索与回放 | 解决: Agent 每轮会话结束即失忆 | 何时选: 要给自建 Agent 接长期记忆时

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages