# Memoturn Db

> Memory for AI agents — an agent-memory database: typed memories with supersession, hybrid recall, and a mind you can checkpoint, fork, and rewind. Rust data plane embedding libSQL.

- **Type:** MCP server
- **Install:** `agentstack add mcp-blakebauman-memoturn-db`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [blakebauman](https://agentstack.voostack.com/s/blakebauman)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [blakebauman](https://github.com/blakebauman)
- **Source:** https://github.com/blakebauman/memoturn-db

## Install

```sh
agentstack add mcp-blakebauman-memoturn-db
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Memoturn

**Memory for AI agents.** Memoturn gives every user, team, or agent persona an isolated **memory
profile** that all of their agents share: typed memories (facts, events, instructions, tasks) with
supersession — newer facts replace older ones on the same topic, history preserved — idempotent
ingest, and hybrid recall (keyword + topic + vector, rank-fused). Profiles are organized as
`namespace > profile > memory`, and no data ever crosses a profile boundary.

Underneath, each profile is its own tiny database — instantly provisioned, near-zero cost when
idle, holding every shape of agent state (memories, documents, KV, vectors, conversation
transcripts, SQL) in a single unit that replicates, branches, and rewinds together. **Memory you
can checkpoint, fork, and rewind**: snapshot an agent's mind before a risky run, rewind if it
learned garbage, burner-branch a session and discard it.

> Status: **architecture + working prototype.** All planned prototype milestones are built and
> tested (67 integration tests incl. the memory layer, request-surface hardening regressions,
> and true multi-node distribution — ownership, forwarding, failover, fencing — against a real
> etcd). See [docs/architecture](docs/architecture/00-overview.md).

## Agent memory in 30 seconds

```bash
# every agent serving acme's user "alice" shares one profile
memoturn memory ingest acme alice --type fact --topic user.diet \
  --summary "vegetarian since 2024" --keywords "food preference"

memoturn memory recall acme alice "what can this user eat?"
# → ranked memories with channel attribution; superseded facts hidden

memoturn token create-ns acme --scope write     # one token, every acme profile
```

Same surface over HTTP (`/v1/memory/{ns}/{profile}/...`), MCP tools
(`memory_ingest` / `memory_recall` / `memory_forget`), and SDKs. Extraction and embeddings are
bring-your-own by default; opt in per node to **server-side extraction**
(`MEMOTURN_EXTRACT_API_KEY` → `POST .../extract` distills raw transcripts into typed memories)
and **auto-embedding** (`MEMOTURN_EMBED_API_KEY` → bare-text ingest and recall get the vector
channel automatically; `MEMOTURN_EMBED_PROVIDER` = `voyage` or `openai`, the latter reaching any
OpenAI-compatible server including a local one) — both run outside the write path.
Full spec: [docs/architecture/07-agent-memory.md](docs/architecture/07-agent-memory.md).

## Measured (prototype, single node, in-process object store)

| metric | target | p50 |
| --- | --- | --- |
| memory ingest (typed fact, 256-dim embedding, supersession) |  profile > memory`) |
| Memory that evolves without losing history | Typed memories with **supersession** by topic key; idempotent content-addressed ingest; hard-delete only on explicit forget |
| Relevant recall, not keyword grep | Hybrid recall: FTS + topic lookup + vector ANN, reciprocal-rank fused, channel-attributed — and empty when nothing matches |
| State per agent/session, not per app | DB-per-profile: provisioning is a metadata write (~ms), idle DBs hibernate to object storage at near-zero cost |
| JSON-native, schema evolves constantly | Document-first API (Mongo-style collections on JSONB) with SQL escape hatch |
| Scratchpads, caches, flags | First-class KV namespaces with TTL and edge-cached reads |
| Safe experimentation | O(1) copy-on-write **burner branches**: checkpoint/fork/rewind an agent's whole memory |
| Tool-native access | First-class MCP server; agents ingest and recall memory as tools |
| Built-in expertise | Embedded AI assistant (NL→query, schema advice, ops copilot) |
| Production operation | Fail-closed auth (Ed25519 JWTs + platform key), deleting a profile revokes its stale write tokens, SQL guard walls off reserved tables, request limits on body/concurrency/control rate, opt-in `durable` write mode |

## Architecture in one paragraph

A Rust data-plane node (`memoturnd`) embeds libSQL and hosts millions of tiny databases in three
temperature tiers (hot/warm/cold). **Object storage is the source of truth** — nodes are
disposable. Committed transactions are shipped as immutable page segments to object storage and
streamed to read replicas; branches are O(1) manifest operations with epoch fencing; a writer
lease per database (etcd) gives single-writer SQL semantics with ≤15 s failover. Writes ack on
local commit by default and ship asynchronously; `MEMOTURN_DURABILITY=durable` (or a per-request
`Memoturn-Durability: durable` header) acks only after the segment is shipped and the manifest
CAS lands. Unreferenced objects are reclaimed by a refcount GC that is safe under copy-on-write
forks. The whole stack deploys with one Helm chart — hardened by default (non-root, read-only
rootfs, NetworkPolicy egress lockdown) — to any Kubernetes (EKS/GKE/AKS/self-hosted).

Full design: [docs/architecture](docs/architecture/00-overview.md) · decisions: [docs/adr](docs/adr).

## Repository layout

```
crates/            Rust workspace: engine, replication, docstore, kv, control, api, memoturnd, cli
mcp/               MCP server (TypeScript)
sdk/typescript/    @memoturn/sdk — TypeScript client (memory + substrate)
sdk/python/        memoturn — Python client (httpx)
deploy/helm/       Helm umbrella chart (kind-deployable)
bench/             Benchmark harness (success-criteria table)
examples/           memory-agent — the product loop as a runnable chat agent
docs/site          docs.memoturn.ai (Astro Starlight; publishes only docs/site/src/content/docs)
docs/architecture  The architecture document set (internal, not published)
docs/adr           Architecture decision records (internal, not published)
```

## AI owns the code; people bring expertise

In the old days, circa 2014, we used to say that developers should not tag themselves as
authors of code in order to encourage team ownership. Now AI owns the code. This code base is
designed to be maintained by AI under human guidance, and we want the LLM to have as much
context as possible. To aid this:

- All artifacts live in the code base — including the architecture docs, ADRs, and deployment
  proofs written for humans ([docs/](docs/)), and the published documentation site
  (docs.memoturn.ai builds from [docs/site](docs/site)). [CLAUDE.md](CLAUDE.md) is the
  AI-facing guide.
- Individuals are not the owners of sections of code. There are no CODEOWNERS, no author
  tags, no per-file attribution — and there should never be.

## Development

The working loop, toolchain, and versioning policy live in
[docs/development.md](docs/development.md); `make help` lists the task-runner targets
(`make check` before pushing). Env vars: copy [.env.example](.env.example).

```bash
cargo build                # build the workspace
cargo test                 # unit + integration tests (67 cross-crate)
cargo run -p memoturnd     # single node on :8080 (data ./data, objects ./data/objects)
cargo run -p memoturn-cli -- memory ingest acme alice --summary "..."   # memory/db/branch/sql/kv/sync
scripts/demo.sh            # the agent-story walkthrough against a running node
cd mcp && npm i && npm run build   # MCP server: node dist/index.js (stdio) or --http 8765 (streamable HTTP)
cd docs/site && npm i && npm run dev   # docs.memoturn.ai locally (deploy: npm run deploy)
helm lint deploy/helm/memoturn     # kind-deployable chart (memoturnd + MinIO)

# auth (off by default in dev): per-database Ed25519 JWTs + platform key.
# Fail-closed: MEMOTURN_AUTH=on requires MEMOTURN_PLATFORM_KEY and a signing-key
# source (MEMOTURN_AUTH_KEY from a secret, or MEMOTURN_PERSIST_AUTH_KEY=1).
# MEMOTURN_AUTH=on MEMOTURN_PLATFORM_KEY=... memoturnd
# memoturn --platform-key ... token create agent-1 --scope write
# memoturn --token  kv put agent-1 scratch plan "..."

# multi-node: point nodes at etcd + shared object storage. Without MEMOTURN_ETCD
# a node that looks multi-node refuses to start unless MEMOTURN_SINGLE_NODE=1.
# docker run -d -p 2379:2379 quay.io/coreos/etcd:v3.5.21 etcd \
#   --listen-client-urls http://0.0.0.0:2379 --advertise-client-urls http://0.0.0.0:2379
# MEMOTURN_ETCD=http://127.0.0.1:2379 MEMOTURN_OBJECT_STORE=s3://bucket ... memoturnd
# real-etcd integration tests are gated on the same endpoint:
# ETCD_ENDPOINTS=http://127.0.0.1:2379 cargo test -p memoturn-api --test distribution_etcd
```

## Names

**Memoturn** — the database and company (memory × conversation turns).
**Burner branches** — ephemeral copy-on-write forks that auto-expire.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [blakebauman](https://github.com/blakebauman)
- **Source:** [blakebauman/memoturn-db](https://github.com/blakebauman/memoturn-db)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-blakebauman-memoturn-db
- Seller: https://agentstack.voostack.com/s/blakebauman
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.