Memstead

Typed project knowledge for AI agents. Memstead is a local engine that keeps an AI agent's project knowledge (decisions and their reasons, specifications, how the parts fit) as a mem: typed markdown files in a folder of your project or on a branch of a git repository you own, readable by you and diffable in review, with no database and no vendor lock-in. A schema you control declares what may be written; the engine checks every write against it and refuses one that does not conform, naming what is missing, so the agent can write it again with the fix. Agents read and write the mem over MCP (the Model Context Protocol), from Claude Code, Codex, Cursor, Gemini CLI or any MCP client; people and scripts use the memstead CLI. The path: install the binaries, run memstead quickstart --repo . in your repository, restart the agent session, let the agent write its first entities, and ask about them in a fresh session.

Under the hood: each mem is a typed graph of interconnected entities. A schema you pin defines the entity types, their sections, and the relationships allowed between them: knowledge, plans, specs, inquiry, or any mix. Knowledge graphs are one well-known slice; Memstead generalises across all of them.

Use it for software specs, ADRs, decision logs, ontologies, research notes, or any domain you define. New here? The glossary defines the terms everything else assumes.

Memstead sits next to the agent-memory tools but works differently. Agent memory is what an agent gathers from its own sessions, automatically. A mem gathers nothing by itself: every entity in it is a deliberate write, by your agent or by you, and a write the schema refuses never lands. The tool-by-tool comparison is in PRIOR_ART.md.

Status: pre-1.0. APIs, schemas, file formats, CLI flags, and the wire shape of MCP tools and HTTP endpoints may change without notice. Not yet stable. Back up your data before exercising mutation operations. See LICENSING.md for per-folder licenses and SECURITY.md for vulnerability disclosure.

Quickstart

Get from nothing to your own graph in a few minutes. (The getting-started guide is the full tutorial version of this section.)

1. Install the binaries. The install script fetches the latest release binaries: memstead (the CLI) and memstead-mcp (the MCP server agents connect to):

curl -sSf https://memstead.com/install.sh | sh

Or via Homebrew (macOS / Linux):

brew install memstead/memstead/memstead-cli memstead/memstead/memstead-mcp

Or build from source: with the Rust toolchain installed, run ./build-engine.sh from a clone of this repo; it compiles the workspace and installs both binaries to ~/.cargo/bin. Whichever path you took, memstead --version should now work.

Every release archive on the releases page carries a SHA-256 checksum and a signed build-provenance attestation; check where a downloaded archive was built with gh attestation verify <archive> -R memstead/memstead (needs the GitHub CLI).

The two products are also on crates.io, so cargo install memstead-cli and cargo install memstead-mcp work: memstead-cli and memstead-mcp. The other crates are published only because they are their dependencies, with no API promise: memstead-base (the engine kernel), memstead-schema, memstead-git-branch (the git-backed storage backend) and memstead-projection (the maintenance loop that keeps a bound mem current with its source). They ride the engine's version line, so a set pinned to one version works together, but they are pre-1.0 and change without deprecation cycles whenever the products need it. The binaries above stay the supported way to install Memstead.

2. Bootstrap a workspace. Either in a fresh directory:

mkdir my-graph && cd my-graph
memstead quickstart

…or in the repository you already have:

cd my-existing-repo
memstead quickstart --repo .

One run leaves a working graph: a workspace, a mem pinned to the built-in default schema, a seed entity, and the MCP wiring for the agent(s) you pick (Claude Code, Codex, Cursor, Gemini CLI; pass --agent <target> to skip the prompt). It prints each artifact it created plus the single next action.

--repo . adds one thing: a source binding over that repository, so the mem has a subject to grow into. The mem takes a folder of its own inside the repo (your files are never adopted as entities), and the receipt states exactly what the starter mem holds, what it does not, and the command that starts the ingest loop. Nothing is ingested during quickstart itself; see Growing a mem from a source.

Prefer the strict, script-safe variant with no side effects beyond .memstead/? That's memstead init --name my-graph --schema [email protected].

3. Add knowledge, find it back:

This is the beginning of the README. Read the rest at the original. Read the full README ↗