Mazarbul

Mazarbul

The system of records for the era of agents.

Local-first, git-native memory and structured data for your AI agents. One Go binary. Talks [MCP](https://modelcontextprotocol.io). Your data never leaves your machine.

What is Mazarbul

Your agents have anterograde amnesia. They forget everything between sessions, so you re-explain your codebase, your preferences, and your decisions every single time. The usual fixes do not hold: a CLAUDE.md caps out and goes stale, a markdown vault is not a database, and cloud memory is an opaque blob you cannot query, audit, or own.

Mazarbul is the place your agents remember. A single local binary, maz, that any MCP-aware agent (Claude Code, Cursor, your own) talks to. Under the hood it is an append-only, cryptographically signed event log, projected into a graph, a vector index, and full-text search, and synced over plain git. Every fact carries its source. Nothing phones home.

It is both a memory for free-text episodes and a real database for typed entities, relations, and facts you can query. Think of it as a personal knowledge graph, a CRM, a decision log, and an agent memory, in one file you own.

And it runs headless. One lean binary gives you a CLI and an MCP server, with no separate database server to stand up and no UI required. So anything that needs to persist structured or unstructured data can lean on it: an agent over MCP, a script or cron job that shells out to maz, or you at the command line. Mazarbul is a local data layer you can drop into virtually anything.

What makes it different:

• Event-sourced and signed. Every memory is an immutable, ed25519-signed event. The log is the source of truth; the indexes are rebuildable derivatives. Nothing is silently overwritten.
• Four-layer hybrid recall. Vector similarity, full-text BM25, graph traversal, and name-embedding, fused into one ranked result with the score breakdown visible.
• Git-native, conflict-free. Plaintext JSONL syncs over any git remote. Two devices converge by construction (CRDT), so concurrent writes never overwrite each other.
• Provenance and audit on every fact. maz blame shows who changed what and when, like git blame for your agent's memory. No other memory layer treats this as first-class.
• Structured and unstructured. Free-text remember, plus typed entities, relations, and facts you define and query. A database, not a pile of notes.
• Reference your live tools, don't copy them. Your agent is already connected over MCP to Notion, Linear, Drive, and more. Mazarbul indexes them with a pointer, a short summary, and a freshness anchor, never the body, so recall spans your own memory and your live sources at once with nothing duplicated.

Your agent is the brain, Mazarbul is the memory

The agent that calls Mazarbul over MCP (Claude Code, Cursor, your own) is already a strong model, so let it do the reasoning. It decides what is worth remembering, writes entities, relations, and facts with the structured tools (createEntity, relate, fact), resolves duplicates, and answers your questions from what recall and getContext return. Mazarbul stores, indexes, recalls, and proves where every record came from. That is why maz init configures no server-side chat model by default: you need only a small local embedding model for semantic recall, not a second LLM. A server-side model (Anthropic or a local Ollama model) is an optional extra that helps only when no agent is in the loop: passive file watching, connector ingestion, maz ask from a plain terminal, and background consolidation.

Install

curl -fsSL https://raw.githubusercontent.com/mo-cmyk/mazarbul/main/scripts/install.sh | sh

Or with Homebrew (macOS and Linux):

brew install mo-cmyk/mazarbul/maz

The installer verifies the download checksum, places maz plus its bundled engine library and man pages, and sets up a local model provider (it installs Ollama and pulls the embedding model semantic recall needs, unless you opt out with --no-ollama). It pulls no chat model: your agent does the reasoning. Then run maz init. If you want Mazarbul to reason on its own as well (agent-less ingestion, maz ask), add --with-chat-model to the installer for a local model, or run maz init --provider anthropic --api-key ... for a remote one.

MCP Registry / one-click bundle. Every release ships a mazarbul_ _ _ .mcpb MCP Bundle per platform that Claude Desktop and other MCPB clients install directly. It runs maz mcp serve against your default data dir, so it shares memory with the CLI (run maz init once to pick a provider). Each release is also published to the official MCP Registry as io.github.mo-cmyk/mazarbul, which registry-aware clients and directories pick up.

Build from source

# Prerequisites: mise (https://mise.jdx.dev), git.

git clone https://github.com/mo-cmyk/mazarbul.git cd mazarbul mise install # provisions Go, golangci-lint, lefthook, vhs, ... mise run setup # go mod download + engine lib + hooks mise run build # builds ./bin/maz (with sqlite_fts5) ./bin/maz --help

maz dynamically links a small native graph engine (LadybugDB), resolved via an rpath into your Go module cache, so a source build runs on the machine that built it. For a self-contained, relocatable binary that bundles the engine, use the installer above.

Quickstart: zero to agent memory

# 1. Initialize your Book: pick a data dir; keep the default "no server-side

chat model" (your agent reasons) or opt into one. Turn on encryption and

init shows a recovery Watchword to save (your only key).

maz init

2. Wire it into Claude Code over MCP. --capture records each session passively;

--warm-start injects a context brief when a new session begins.

maz connect claude-code --capture --warm-start

3. Remember something. Over MCP your agent also writes the entities and

relations it sees; with a server-side chat model, maz extracts them too.

maz remember "Frodo Baggins works at Bag End in the Shire as a ring-bearer."

4. Recall it. Hybrid search (vector + full-text + graph + name-embedding), scored.

maz recall "where does Frodo work"

That is it. Claude Code now has a recall and remember tool pointed at your Book, and every session it works in gets remembered and fed back. Any other MCP agent connects the same way via maz mcp serve.

How it works

The event log is the source of truth. Everything else is a rebuildable projection of it.

flowchart TD

A["maz remember / relate / fact (CLI, MCP, ambient hooks)"] --> B

subgraph SOT["Source of truth"] B["Signed, append-only JSONL event log (ed25519 author on every event)"] end

B --> D{{"Dispatcher (the only writer to the projections)"}}

subgraph PROJ["Rebuildable projections (maz rebuild)"] direction LR E["SQLite relations + facts"] F["LadybugDB graph traversal"] G["sqlite-vec semantic recall"] H["FTS5 keyword / BM25"] end

D --> E & F & G & H

E & F & G & H --> I["Hybrid recall (4 lanes, fused + scored)"]

I --> J["Surfaces MCP (agents) | CLI / TUI (humans)"]

B -. "seal + push (plaintext JSONL

• rendered markdown tree)" .-> K[("Any git remote

conflict-free / CRDT")] K -. "pull (no LLM re-extraction)" .-> B

Because the log is append-only and every event is immutable and signed, two devices that sync the same log converge to byte-identical state. There is no last-write-wins overwrite. If any index is ever corrupted, maz rebuild reconstructs all four from the log.

A database for your agents, not a pile of notes

This is the core of it. Mazarbul stores free text *and* structured data, and lets you query both.

# Define a typed entity kind and a custom relation, on the fly. An agent can do

this over MCP too; the ontology is data, so it syncs and versions like the rest.

maz schema kinds add artifact --display-name "Artifact" --description "An object of power" maz schema predicates add bears --description "carries an object of power"

Preview what defineEntityKind would do before committing (mint / collapse / supersede):

maz schema preview kind artifact --description "An object of power"

Mint structured entities with typed properties, then wire the graph by name.

relate takes names or ULIDs and requires both endpoints to already exist.

maz entity create person "Frodo Baggins" maz entity create artifact "The One Ring" --attributes '{"forged_in":"Mount Doom","power":"invisibility"}' maz relate "Frodo Baggins" bears "The One Ring"

Read it back: typed kind, typed properties, provenance, and the new relation.

maz get "The One Ring" maz neighbors "Frodo Baggins"

Assert a scalar fact with history. Later writes supersede the value but keep the

old one, so you can still ask where the Ring-bearer was earlier in the journey.

maz fact set "Frodo Baggins" location "Rivendell" maz fact get "Frodo Baggins"

Close a fact that stopped being true (keeps history), or hard-delete one outright.

maz fact retract "Frodo Baggins" location # slot reads empty after; history preserved maz forget facts/01ARZ3NDEKTSV4RRFFQ69G5FAV # remove a fact row entirely

Query the lot with one hybrid recall over structured data and free text, and

pin the view to a point in time (valid-time).

maz recall "who carries the ring" maz recall "who carries the ring" --at 2026-01-01T00:00:00Z # facts as they were valid on Jan 1

Pure markdown cannot query, join, or track change. Pure vector search cannot connect facts across documents. Mazarbul gives you typed entities and relations with a queryable graph, *and* the free-text episodes, fused in one recall.

What you can do

Mazarbul is a universal, headless data layer and system of record. The same primitives become many tools:

• Agent memory. The default. remember facts, recall them across sessions. Stop re-explaining your project to every agent.
• Notes and knowledge vault. maz doc import ~/notes pulls your markdown in; wikilinks resolve to entities; maz doc log and maz doc diff give every note a history.
• Personal CRM. People, organizations, and the relations between them (works_at, reports_to, introduced_by). Capture how and why you met someone, not just a name.
• Decision log / ADRs. Append-only by design, with supersede links. The reasoning behind a decision survives, and stays queryable, long after you would have forgotten it.
• Knowledge graph. Define domain kinds and predicates, install schema packs, and traverse the result.
• Team brain. A shared, end-to-end-encrypted scope so a whole team's agents draw on the same memory.

Draft staging: stage before you commit

Sometimes you want to capture something without immediately making it part of your perm