Weft

Getting started

Five steps, about five minutes. At the end you'll have a shared brain that any agent — on any machine — can read and write.

Prerequisites. Python 3.12+ and uv. Docker Desktop is needed only for weft up (local Postgres + Redis) and the database-backed test suite. Only Docker is supported at this time.

01Install Weft

Recommended: pipx, for system-wide availability.

pipx install git+https://github.com/MennoAf/weft.git

Or as a uv tool:

uv tool install git+https://github.com/MennoAf/weft.git

For local development, clone and sync instead:

git clone https://github.com/MennoAf/weft.git && cd weft && uv sync

02Start infrastructure

One command launches Weft's local infrastructure — Postgres 16 with pgvector on port 5433 and Redis 7 on port 6380 — then runs migrations. 

weft up

03Register Weft as an MCP server

Add the Weft MCP server to your agent harness, using the harness's own MCP documentation for its configuration format. Then give your agent the copy-paste memory protocol so it uses Weft tools instead of flat-file memories.

Claude-specific setup lives in the repo's CLAUDE.md; harness-neutral connection steps are in the agent wiring guide.

You'll also want prime and handoff as skills your agents can access — ready-made copies are in templates/commands/.

04Point your agent at Weft

With the protocol in place, the agent saves with weft_remember, recalls with weft_recall, and treats flat files as fallback-only. A quick way to verify the override stuck:

Ask your agent: “Without me telling you, where do you save memories?”
Expected answer: “Weft, via weft_remember. The flat-file system is fallback-only.”

05First session

Start a session and ask the agent to call weft_prime(disclosure="progressive"). It loads any saved context, or reports that none is available yet.

Memories are scoped per project, and a project is just a name: pick one name per repo and stick to it. Tell your agent to save a memory, for example: 

Save: I prefer test descriptions in the form "test_<thing>_<condition>_<outcome>"

Then write the project name into the repo's AGENTS.md (or your harness's equivalent instructions file), so every agent that works in this repo — on any machine — loads and saves to the same brain. At the end of a non-trivial session, ask it to call weft_handoff; a later session's weft_prime will surface both.

Going deeper

Every tool and parameter: docs/tools.md. Every CLI command: docs/cli.md. Configuration, environment variables, and infrastructure: docs/configuration.md.