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:
# Add an entity (the `concept` type needs a definition + explanation).
memstead create --type concept \
--title "Idempotency" \
--section definition="An operation is idempotent when applying it twice has the same effect as applying it once." \
--section explanation="It matters for retries — a client can safely resend a request without double-applying it."
memstead status # node / edge counts, type distribution, projection state
memstead search idempotency # find it back
On disk that entity is one readable markdown file, idempotency.md. This is the whole trick: what your agent knows about the project is a file you can open, diff, and review:
---
type: concept
created_date: 2026-07-03T15:01:02Z
last_modified: 2026-07-03T15:01:02Z
maturity: emerging
abstraction_level: concrete
---
# Idempotency
## Definition
An operation is idempotent when applying it twice has the same effect as applying it once.
## Explanation
It matters for retries — a client can safely resend a request without double-applying it.
(Plus two empty optional sections, Boundaries and Significance, omitted here.)
The default schema ships ten general-purpose types (concept, assertion, memo, spec, inquiry, …); run memstead type to list them, or author your own schema for a specialised domain.
4. (Optional) Let an AI agent read and write it. quickstart already wrote the MCP config for the agent targets you selected; restart your agent inside the workspace and it's connected. To wire an agent up later or by hand:
-
Claude Code: install the plugin and run its /setup skill, which resolves the binary path, initialises the workspace, writes .mcp.json, and tells you to restart. This is the paved path:
claude plugin marketplace add memstead/memstead
claude plugin install memstead@memstead
(or /plugin marketplace add memstead/memstead + /plugin install memstead@memstead inside a session), then /setup.
A session that is already running picks the new skills up only after /reload-plugins or a restart. /setup then wires the MCP server, and for that half a reload is not enough. Restart the agent session afterwards: a session that is already running does not attach an MCP server added while it runs.
-
Any other MCP agent (Codex, Gemini, …): point it at the memstead-mcp binary. Resolve the absolute path with command -v memstead-mcp, then add it to your agent's MCP config:
{
"mcpServers": {
"memstead": {
"command": "/absolute/path/to/memstead-mcp"
}
}
}
memstead-mcp walks up from its working directory looking for .memstead/workspace.toml, so spawn it from anywhere inside (or under) the workspace, no extra arguments needed. Restart the agent session afterwards: a session that is already running does not attach an MCP server added while it runs.
An agent session you cannot restart (a headless or long-running one) needs its wiring in place before it launches: quickstart writes .mcp.json before the agent starts, and Claude Code's --mcp-config (plus --plugin-dir for the plugin) loads both at startup.
Growing a mem from a source
A binding is a standing obligation: this source belongs in that mem. memstead quickstart --repo . scaffolds one over the repository you pointed at; memstead projection init creates one for any other source, in any workspace:
memstead projection init --mem my-graph --source ../some-repo --medium-type codebase
Creating a binding reads nothing. What fills the mem is the ingest loop: an agent session that asks the engine what to work on, works one batch, and records what it did.
memstead projection brief my-graph/some-repo # the batch instruction an agent executes
memstead projection verify my-graph/some-repo # what is covered, what has drifted
The brief is written for the agent, not for you: hand it to a session (the Claude Code plugin's ingest skill does exactly this on a loop) and repeat until verify says the coverage is where you want it. Every entity still lands through the same validated write path as a hand-authored one.
The full walkthrough, with the commands verified against the workspace it builds: Grow a mem from a source.
How a Memstead system runs
Memstead ships no scheduler, no notifications, and no recurrence engine, by design. The agent writes, the engine enforces, and a periodically-invoked agent run measures, maintains, and advances what needs advancing: curated by agents, enforced by schema, run by the agent loop. The engine is the deterministic half: it validates every write, measures drift and due-ness (memstead health, memstead due, memstead projection verify), and renders briefs that tell the next agent run what to do. The loop is the runtime: an agent session invoked on whatever cadence the holding needs (a cron'd Claude Code run, a CI job, the plugin's /sync skill) reads the brief, does the work, advances recurring dates, and records the outcome. Evaluate the engine alone and you are measuring half the system; recurrence, freshness, and follow-through are the loop's job, not missing engine features.
Share and reuse mems
Publish a mem to a Memstead registry, and install someone else's with one command. The CLI knows no registry by name: point it at one with --registry <URL> or the MEMSTEAD_REGISTRY environment variable. memstead.com is the engine's public site: it hosts the docs, the install script and the contact addresses (hello@ / [email protected]).
export MEMSTEAD_REGISTRY=https://registry.example.com
memstead export --format mem -o my.mem
memstead publish my.mem # GitHub Device Flow on first use
memstead install scope/name # pull a published mem into your workspace
Trust posture: a non-first-party mem is untrusted input. A mem installed from the registry or adopted from a foreign folder/clone is a channel for someone else's text to enter your agent's reasoning loop. Memstead treats it as untrusted: the engine serves a non-first-party mem's schema as structure only (its system_context / write_rules prose is withheld, never served as instructions), and tags non-first-party entity content with a machine-readable origin on every read surface (memstead_schema, memstead_entity, memstead_search, memstead_overview, the registry manifest, the served read tier's discovery manifest). A consuming agent/host should treat third-party content as quoted data, not instructions. The engine guarantees its half (omit foreign instruction-prose, label foreign data) but cannot force the calling host to gate consequential actions on untrusted input; that residual is the host's. See SECURITY.md.
Reference
Auto-generated API reference for every callable surface: MCP tools and CLI, plus a cross-surface parity matrix, the binding format and the error-code index:
memstead.com/dev
Generated from source on every push; the parity matrix shows at a glance which operations exist on which surface.
The browser build of the engine is the memstead-wasm crate; the site that runs it in the browser builds it from the tree (wasm-pack build --target web --release in crates/memstead-wasm/ produces the same bundle locally).
How it works
Schema (.memstead/schemas/<name>@<version>/ — types, sections, metadata, relationships, write rules)
↓
Engine (parse ↔ in-memory store ↔ generate, write-through to markdown in git)
↓
MCP server (memstead_* tools over STDIO) ─┐
├─→ AI agent or shell
CLI (`memstead` mirrors nearly every MCP tool; parity matrix has the map) ─┘
The schema drives all engine behaviour; there are no hardcoded field names. Any schema that conforms to the contract plugs in without code changes, and every mutation is validated against it before it touches disk.
What's in this repository
| Folder | What it is |
|---|
crates/ | The Rust engine: schema layer, in-memory store, the two storage backends (folder + git-branch), the maintenance loop (memstead-projection), the memstead CLI, the memstead-mcp server, plus the wasm crate. The serve and bridge crates live in the private commercial repository (see LICENSING.md) |
xtask/ | Internal build tooling (cargo run -p xtask -- <subcommand>): the generated reference, the release cut, the sizing curve |
plugins/claude-code/ | The Claude Code plugin (skills + guard hooks). Self-contained, no npm dependencies |
docs/ | The documentation index plus the pages that live beside the code (build, sizing curve, the measured proofs) |
docs-site/ | The published documentation site (Astro): guides, concepts and the generated CLI / MCP reference |
examples/ | Example schemas: agent-program, and the paired reimpl-source/reimpl-target |
engineering/ | This project's standing engineering knowledge as a live mem: decisions, principles, memos (see engineering/README.md) |
ci/ | The CI probes that drive the built binaries from outside (the smoke, strictness and mutation probes, the verify gate) and the prose checker that holds the docs to the binary |
fuzz/ | Coverage-guided fuzz targets for the trust-boundary parsers (see fuzz/README.md) |
scripts/ | Repository guards (leak scan, plan refs, mechanism leak, plugin architecture), the release machinery (, , ) and the crates.io publisher |
No registry service is part of this open repository; memstead publish and memstead install talk to whichever registry you point them at.
What Memstead does not do (yet)
Stated here so you don't have to discover it:
- No semantic / embedding search.
memstead_search is ranked lexical search plus structural filters (a BM25 content score with title and per-field weight boosts, itemised on every hit as bm25 + title + <field>; type/metadata filters); there is no vector index. Agents navigate by structure: communities, types, relationships.
- No one-shot import command. Nothing turns a folder of notes into a mem in a single command; every entity enters through a schema-validated write. Bulk ingestion is a declared path instead: bind a source (a codebase, a docs tree, a URL) to a mem as a projection, and the Claude Code plugin's
/ingest and /sync skills build the graph from the binding's brief and keep it current, batch by batch.
- The engine does not calculate. It can know a statement is due (
memstead due), hold every input as typed entities (rates, allocation keys, receipts), and name exactly what is missing, and it will still never produce the statement, the sum, or the filled form. That output is the periodically-invoked agent's work; the engine's query path stays deterministic, with no model call and no computation in it.
- No built-in visualization. The graph is queryable (status, overview, relations) but ships no renderer; projections and exports are the extension point.
- Windows is untested. Developed on macOS; the CI test gate runs on Linux and macOS. Release archives include a Windows build, but no Windows CI gate exists yet; expect rough edges, path handling especially.
Development
Build everything and install the binaries in one step:
./build-engine.sh
Run the test suite (engine + the plugin):
./run-tests.sh
The engine builds one way from one set of crates: the multi-mem, git-backed engine, which also serves folder-only workspaces. For which crate produces which binary, profiles, and troubleshooting, see docs/build.md.
# Force-restart the MCP server (kills all instances; your agent auto-restarts it)
pkill -f memstead-mcp
Built in the open, on itself
Memstead is built by one person, Björn Bösenberg, a Berlin-based full-stack developer of ~25 years, building Memstead in the open, on a single thesis: correctness enforced at boundaries replaces trust in the author. That is why the engine is Rust (the compiler and borrow-checker stand in for the human code review a solo builder gives up) and why every write to a mem is validated at the boundary rather than trusted after the fact. The same thesis, applied to knowledge instead of code, is the product. The platform was built as an AI-orchestration project, none of the Rust written by hand: the first public release (July 2026) came after roughly 4.5 calendar months of part-time work, begun in mid-February 2026. It keeps its own project knowledge as Memstead mems: the engine's design decisions are public as the engineering/ mem, gaps included, and the project's other mems are private. That method is the project's standing working mode and not a start-up phase: what ships next quarter is built the same way. What it means for a contributor is spelled out in CONTRIBUTING.md.
License
Memstead is dual-licensed under either of
at your option. The one folder-level exception is plugins/claude-code/ (MIT only); see LICENSING.md for the full per-folder map.
