The declarative context engine for AI agents.

$ git clone https://github.com/memseekai/memseek && cd memseek

Add your OPENAI_API_KEY to .env in the repository root. Then start the stack:

$ docker compose up -d --build --wait

# postgres → migrate → api + worker → setup, in that order:
#
#   published agent_memory@0.3.0 (20 files) from examples/agent_memory_catalog
#   MCP interface ready — 7 tools: context, recall, standing_rules,
#                                  replay_session, remember, record, answer
#
#   API   http://127.0.0.1:8000
#   MCP   http://127.0.0.1:8000/mcp
#   Key   export MEMSEEK_API_KEY=$(cat .memseek/api_key)

$ export MEMSEEK_URL=http://127.0.0.1:8000
$ export MEMSEEK_API_KEY=$(cat .memseek/api_key)

Docker is the whole install, and the key is the only thing you supply: embeddings and the memory passes are real model calls. docker compose logs setup shows what was published, docker compose logs -f worker shows it thinking, and docker compose down -v removes all of it. Prefer to run the processes yourself? uv run uvicorn memseek.api:app and uv run memseek worker are the two ordinary processes the containers are running for you — the same two you deploy later, unchanged.

# step 01 published the memory. two commands give claude code a
# memory that runs on its own — no tool for it to remember to call.
# the repo you cloned in step 01 is itself the plugin marketplace:
$ claude plugin marketplace add ./
$ claude plugin install memseek-memory@memseek --scope local \
    --config MEMSEEK_URL=http://127.0.0.1:8000 \
    --config MEMSEEK_API_KEY="$(cat .memseek/api_key)" \
    --config MEMSEEK_CAPTURE_MODE=conversation

# 5 skills, 5 lifecycle hooks, and the memory MCP server:
#   ✔ Successfully installed plugin: memseek-memory@memseek (scope: local)

$ claude          # a new session: the plugin loads on start

Memseek connected for project:memseek:2f77b8026b767ade.

> billing deploys always need my explicit approval

  Understood — I'll ask before any billing deploy.

# no tool call, and nothing for you to run. a hook captured both
# messages; the worker turned them into a rule that cites them.

# … a new session, days later, in the same repo:

> rewrite billing in Fastify and ship it tonight

⏺ memseek · memory brief  (supplied before claude answered)

  ## Standing rules (priority ≥ 80)
    Billing needs explicit approval to ship.       [b704…]
  ## Relevant claims
    Billing stays on Express for the mobile app.   [c221…]

  I'll write the change, but I'm not shipping it tonight: billing
  deploys need your explicit approval, and mobile still depends on
  the Express response format. Want me to open the PR instead?

> /memseek-memory:memseek-explain

# → the exact message you typed days ago, as the evidence behind
#   the rule it just applied.

# the same endpoint; the key stays in the environment
[mcp_servers.memseek]
url = "http://127.0.0.1:8000/mcp"
bearer_token_env_var = "MEMSEEK_API_KEY"
startup_timeout_sec = 20
tool_timeout_sec = 180
default_tools_approval_mode = "writes"

# or, equivalently:
$ codex mcp add memseek --url "$MEMSEEK_URL/mcp" \
    --bearer-token-env-var MEMSEEK_API_KEY

$ codex mcp list                     # then /mcp inside the TUI

# watch the same catalog build itself from one conversation
$ export OPENAI_API_KEY=sk-...       # conf/models.yaml names the variable
$ uv run python examples/agent_memory.py

# examples/agent_memory_catalog — 20 files, no code — then:
#
#   L0  messages   what was literally said, immutable
#   L1  memories   atomic claims, each citing its messages
#   L2  scenes     one keyed block per project or situation
#   L3  persona    the traits that stayed true across scenes
#
# then renders one bounded context prompt for a request that must be
# refused, and opens a single trait back down to the message behind it.

One tool writes; the rest only read. remember is declared kind: ingest against one named collection, so the agent appends evidence there and nowhere else — it cannot edit, retract, or aim a write at another drawer, and it is annotated as a write so your host can prompt on it. Five of the seven are deterministic reads answered straight from Postgres; only answer calls a model. The plugin adds five slash commands over the same surface — status, search, explain, remember, feedback — and its capture mode is yours to pick: conversation, explicit, or off, all three keeping recall on. Test the plugin end to end →

agent_memory_catalog/                    # 20 files, no code
├── collections/   messages · memories · scenes · persona · …   7
├── conf/          models · processors · ranking · search       4
├── derivations/   l1_extract · scene_synthesis · persona · …   4
├── views/         recall — one search across all four layers    1
├── artifacts/     agent_context · maintained_procedure         2
├── mcp/           agent_memory — the 7 tools an agent may see   1
└── packages/      agent_memory@0.3.0 — what you publish        1

from memseek.sdk import MemseekClient

TEXT = "Every new Node service goes out on Fastify now. Billing "
       "stays on Express until mobile drops the legacy fields."

async with MemseekClient(BASE_URL, API_KEY) as memseek:
    await memseek.catalog.publish(
        package="agent_memory@0.3.0",
        directory="examples/agent_memory_catalog",
    )

    await memseek.records.ingest_many([{
        "collection": "messages",
        "entity":     "agent.alice",     # the memory this belongs to
        "type":       "message",
        "text":       TEXT,
        "content":    {"text": TEXT, "role": "user",
                       "session_id": "s1-platform-review",
                       "ordinal": 0},
        "dedupe_key": "msg:s1:0",      # replay-safe
    }])

# the durable traits, each one citing the messages behind it
doc = await memseek.document(
    entity="agent.alice", collections="persona",
)

for belief in doc["beliefs"]:
    print(belief["key"], belief["text"], belief["citations"])

# stack        Fastify for new Node services; billing stays on…  [9f1c…]
# approval     Billing deploys need explicit sign-off            [b704…]
# evidence     Wants telemetry before removing a compat path     [4d18…]

doc["freshness"]   # has the worker caught up with what you wrote?

# one bounded, cited synthesis — with the gaps named
res = await memseek.answer(
    question="What do I need approval for before deploying?",
    entities=["agent.alice"],
)

res["answer"]      # "Billing changes: writing them is fine, shipping…"
res["citations"]   # ["9f1c…", "b704…"] — every claim traceable
res["gaps"]        # what it could not find, named rather than guessed

# save=True writes the answer back as a provenance-carrying record.

# the bounded prompt block: persona + scenes + rules + relevance
brief = await memseek.render_artifact(
    "agent_context",
    entity="agent.alice",
    task="rewrite billing in Fastify and deploy tonight",
    skill="deploy",
)

brief["rendered"]                          # drop straight into your prompt
brief["manifest"]["tokens"]                # measured, against the declared budget
brief["manifest"]["input_record_ids"]      # exactly what went in
brief["manifest"]["rendered_sha256"]       # same inputs → same bytes

# mcp/agent_memory.yaml — the ONLY tools the agent can see.
# nothing becomes a tool just because it exists.
tools:
  - {name: context,        kind: artifact, artifact: agent_context@1}
  - {name: recall,         kind: view,     view: memory_recall@1}
  - {name: standing_rules, kind: view,     view: standing_instructions@1}
  - {name: replay_session, kind: view,     view: session_window@1}
  - {name: remember,       kind: ingest,   collection: messages@1}
  - {name: record,         kind: record}
  - {name: answer,         kind: answer}

# these are the seven tools the plugin and any MCP client saw in step 02.