convez.ai
MCP ServerAutomaçãoAvançado
memoturn

Memoturn — Memória para Agentes de IA

memoturn/memoturn

Banco de memória para agentes com checkpoint, fork e recall híbrido

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que fornece um sistema de memória persistente e isolado para agentes de IA, com suporte a memórias tipadas, supersessão, recall híbrido (keyword + topic + vector) e operações avançadas como checkpoint, fork e rewind. Implementado em Rust com libSQL, permite que múltiplos agentes compartilhem perfis de memória estruturados com versionamento e histórico completo.

Instalação

$npx convez-ai memoturn/memoturn

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Manter contexto persistente entre múltiplos agentes que servem um mesmo usuário
  • Implementar recall inteligente de informações com busca por keywords, tópicos e embeddings
  • Criar snapshots de estado mental de agentes antes de operações arriscadas e fazer rewind se necessário
  • Gerenciar memórias tipadas (facts, events, instructions, tasks) com supersessão automática

Veredito

Sistema robusto e bem arquitetado para memória distribuída de agentes, com prototipagem avançada (67 testes de integração, multi-node com etcd) e performance comprovada. Ideal para equipes construindo agentes complexos que precisam de memória confiável e reversível; exige compreensão técnica sólida da stack.

README

A tradução para o português deste README ainda está na fila.

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.

Agent memory in 30 seconds

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

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

metrictargetp50
memory ingest (typed fact, 256-dim embedding, supersession)<10 ms3.9 ms
hybrid recall over 10k memories (FTS5 + topic + ANN, rank-fused)<25 ms11.7 ms
provision database<100 ms17 µs
hot KV read / SQL write / doc insert<1 ms / <5 ms / <5 ms3 µs / 16 µs / 15 µs
segment ship (write + WAL capture + PUT)<10 ms61 µs
branch create (copy-on-write)<50 ms47 µs
cold wake (restore + open + query)<200 ms0.7 ms (+object-store RTT in prod)
10k databases provisioned—93 ms (107k/s), hot pool flat

Reproduce: cargo run --release -p memoturn-bench · demo: scripts/demo.sh

Proven on Kubernetes (docs/deployment-proof.md): Helm chart (secure by default: non-root, read-only rootfs, NetworkPolicy; refuses multi-replica without etcd) on kind with MinIO + auth — all HTTP benchmarks pass (provision 1.61 ms, segment ship to MinIO 6.54 ms p50), and the chaos test holds: kubectl delete pod on the data plane → fresh pod with no PersistentVolume serves the same data with the same token in ~15 s.

Why agents need a different database

Agent requirementMemoturn answer
Memory shared across all of a user's agentsOne profile per user/team/persona; agents are clients of the same profile — isolation is structural (namespace > profile > memory)
Memory that evolves without losing historyTyped memories with supersession by topic key; idempotent content-addressed ingest; hard-delete only on explicit forget
Relevant recall, not keyword grepHybrid recall: FTS + topic lookup + vector ANN, reciprocal-rank fused, channel-attributed — and empty when nothing matches
State per agent/session, not per appDB-per-profile: provisioning is a metadata write (~ms), idle DBs hibernate to object storage at near-zero cost
JSON-native, schema evolves constantlyDocument-first API (Mongo-style collections on JSONB) with SQL escape hatch
Scratchpads, caches, flagsFirst-class KV namespaces with TTL and edge-cached reads
Safe experimentationO(1) copy-on-write burner branches: checkpoint/fork/rewind an agent's whole memory
Tool-native accessFirst-class MCP server; agents ingest and recall memory as tools
Built-in expertiseEmbedded AI assistant (NL→query, schema advice, ops copilot)
Production operationFail-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 · decisions: 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/), and the published documentation site (docs.memoturn.ai builds from docs/site). 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; make help lists the task-runner targets (make check before pushing). Env vars: copy .env.example.

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

Ver o original no GitHub

Bom para

Relacionados