Weft

Getting Started

Five steps and about five minutes is all that's between your agent and a memory that persists across conversations, harnesses, and devices.

Prerequisites. Python 3.12+ and uv. Docker Desktop is needed 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 The Weft 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 your Agents.md updated, your agent saves with weft_remember, recalls with weft_recall, treating flat files as fallback-only. A quick way to verify the instructions 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"). If you installed the skills, just use /prime.

The first time you do this, you'll get a notification that there are no memories 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.