Skip to main content
Glama

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. Your data never leaves your machine.

License: Apache 2.0 Go 1.26 MCP Local-first Works with Claude Code

Mazarbul: from zero to an agent that remembers

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.

Related MCP server: agent-memory-os

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_<tag>_<os>_<arch>.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.

# 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<br/>(CLI, MCP, ambient hooks)"] --> B

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

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

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

    D --> E & F & G & H

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

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

    B -. "seal + push (plaintext JSONL<br/>+ rendered markdown tree)" .-> K[("Any git remote<br/>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

Defining a typed kind, minting an entity, and querying it back

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 permanent memory. Write with --scope draft and it lands in a private staging area, invisible to recall, get, and every other read verb until you decide what to do with it:

# Stage privately. Nothing in recall or getContext sees this yet.
maz remember "rough notes from the Prancing Pony meeting" --scope draft

# Review what is staged.
maz scope draft list            # episodes, entities, and relations in staging
maz scope draft diff            # compare draft against your personal set side by side

# Promote into personal memory (now recall-able and sync-able).
maz scope draft promote episodes/01ARZ3NDEKTSV4RRFFQ69G5FAV

# Or throw it away. The audit event is appended; the projection is cleaned up.
maz scope draft discard episodes/01ARZ3NDEKTSV4RRFFQ69G5FAV

Promotion always targets personal (or project). Promoting directly into a shared team scope is refused by design — unreviewed draft data should never land in a shared scope without an explicit team write. Discard removes the episode and all draft entities it created; the event log itself is append-only, so the audit trail is preserved.

Named recall shortcuts

Save a query once, replay it whenever you need it:

maz saved add standup --query "daily standup Berlin team" --limit 5
maz saved list                          # all saved queries
maz saved show standup                  # stored parameters
maz saved recall standup                # run it through the live recall pipeline
maz saved remove standup

Saved queries live in your Book's config.toml under [saved_recalls]. Replaying always hits the live index, so results evolve as new episodes arrive.

Build your own skills and ontology

A preset is a skill for your agent: a schema pack (entity kinds and predicates) plus an instructions.md that teaches the agent when and how to use them. Install one, author your own, or publish it for others.

maz install schema-org-core           # built-in pack: common schema.org types
maz install business-de               # built-in pack: German business + legal types
maz preset install agent-memory       # teaches an agent when to reach for memory
maz preset install second-brain       # life-graph: people, projects, notes, topics
maz preset install decision-trace     # decision provenance: decisions, insights, principles
maz preset install github.com/you/your-preset   # install a preset from any git repo
maz preset package ./my-preset        # validate + print a checksum to publish

Once second-brain is installed, it seeds brain:Person, brain:Project, brain:Note, and brain:Topic kinds with relations like collaborates_on, tagged_with, and inspired_by. Try a recall after adding a few notes to see how the graph organizes them. decision-trace seeds decision, insight, and principle kinds and wires them together with first-class traceability edges.

Define types ad hoc with maz schema kinds add / maz schema predicates add, or let an agent define them over MCP with defineEntityKind / definePredicate. Use maz schema preview kind <name> to see the plan (mint / collapse-into / supersede) before writing. The ontology is data, not code, so it syncs and versions like everything else.

Bring your existing tools

Mazarbul meets your data where it already lives.

# Import an existing markdown / Obsidian vault. Wikilinks become entities;
# bodies become recall-able. Idempotent, so re-running skips unchanged files.
maz doc import ~/ObsidianVault

# Or point Mazarbul's vault straight at your Obsidian folder (it only ever writes
# documents it owns) and edit notes in Obsidian as usual.
maz config set vault.path ~/ObsidianVault

# Render an entity neighborhood as an Obsidian-openable canvas.
maz doc canvas "Frodo Baggins"

# Pull in your other sources. Connectors ingest untrusted external content, so
# the target scope needs encryption enabled first (maz doctor sets it up).
maz source connect local-git --repo .              # your repo's commit history
maz source import claude-chats ~/Downloads/export.zip   # your Claude.ai exports

Importing a markdown vault; wikilinks resolve to entities

This is "Karpathy-style" external memory (an agent that compiles a persistent, interlinked base instead of re-deriving everything per query) with the parts the markdown-wiki approach lacks: a typed query layer, an automatic entity graph, provenance, and a sync that does not corrupt.

Reference live sources instead of copying them

Importing copies data in. The other half is the opposite. Your agent is already connected, over MCP, to the tools your work actually lives in: Notion, Linear, Granola, Google Drive, GitHub. Mazarbul holds no tokens for any of them and never fetches them itself. It indexes them.

After your agent reads an item from one of those tools, a single captureExternal call records a pointer to it, the agent's own short summary, and a freshness anchor (a content hash plus the fetch time). The body never lands in Mazarbul. That summary is then searchable in recall alongside everything else you remember, and every hit grounded in a live source carries an inline freshness verdict and an external-lineage marker:

recall "the Q3 launch plan"
  Q3 launch: connector wave ships first, then the public install path.
    source: notion   freshness: fresh (fetched 2h ago)   trust: proposed

When a hit goes stale (past that connector's freshness budget) the agent re-fetches the live item and re-captures, so the index never drifts from the source of truth. And because the lineage is external rather than authored, these land proposed, untrusted: searchable and rankable, but clearly summarized-from-elsewhere, not something you asserted. See agent-docs/external-references.md.

The result is one place to search across your own memory and your live tools at once, with no second store to keep in sync.

It's just git

Your memory is plaintext JSONL plus a rendered markdown tree in a normal git repo. Inspect it with semantic, entity-aware commands, or with the git you already know.

# Seal local memory into signed chunks and push to your git remote.
maz sync push

# Browse it semantically, from anywhere:
maz diff HEAD~5..HEAD         # what changed: entities added, relations superseded
maz diff --kind person --operation changed --format json   # changed person entities as JSON
maz blame "Frodo Baggins"     # who changed this entity, and when
maz changelog                 # per-push summaries, newest first

# Or clone the synced repo and use plain git. It is JSONL plus a rendered markdown
# tree, so log, diff, and blame all just work on it:
git clone <your-remote> memory && cd memory
git log --stat
git blame rendered/by-uid/<...>.md   # line-level provenance, in plain git

maz diff also takes --predicate and --operation post-filters. JSON output (--format json) surfaces a filtered count and an active_filters map alongside the entries, so scripts can assert what changed without parsing prose.

Bulk import and re-embedding

Moving machines, restoring from a backup, or switching embedding models? Two commands cover it:

# Bulk-load a JSONL snapshot exported with "maz export".
maz load backup.ndjson                    # append every event (default)
maz load backup.ndjson --mode merge       # skip events whose UID already exists (idempotent)
maz load backup.ndjson --dry-run          # parse + validate, report counts, write nothing

# After switching embedding models, re-embed every episode.
maz reindex --reembed                     # drop episodes_vec and rebuild it
maz reindex --reembed --dry-run           # count what would be re-embedded first

maz load emits {mode, source, total, appended, skipped, invalid, dryRun}. Warning MAZ-LOAD-001 fires when merge mode skips duplicate UIDs; MAZ-LOAD-002 when a line is malformed. The batch is atomic: either all valid events land or none do. maz reindex --reembed requires an embedder configured (maz init --embed=ollama); the other three derived stores (SQLite, graph, FTS5) are untouched.

Both maz rebuild and maz reindex --reembed run with the daemon up. No maz daemon stop is required. When the daemon is running, the CLI routes these operations to the admin HTTP interface (POST /admin/v1/rebuild, POST /admin/v1/reindex), which is exposed only on the Unix socket, not TCP. The daemon builds a shadow projection in a temporary directory, quiesces for a brief swap window (seconds), renames the new indexes into place, and resumes serving on the same socket. The reconnecting maz mcp serve proxy masks the window for read traffic; in-flight writes fail clean and can be retried. maz reindex --dry-run is unavailable while the daemon runs (it requires in-process store access). The same socket-only /admin/ surface is how maz preset install, maz preset uninstall, maz load, and maz schema alias operations route privileged writes through the live daemon.

maz sync log, semantic diff, and per-entity blame on the git-tracked tree

Markdown vaults synced over git overwrite each other on concurrent writes. Mazarbul's log is conflict-free by construction, so two machines pushing at once converge instead of clobbering. For an untrusted host, turn on per-scope encryption (XChaCha20-Poly1305) and the repo holds only sealed ciphertext.

Why Mazarbul

You are probably already doing this with one of these. Here is what Mazarbul gives you instead.

  • Obsidian + Claude Code + git. You get markdown silos, manual linking, no query or join, git sync that corrupts on concurrent writes, and provenance only if you hand-enforce it. Mazarbul keeps the git-native plaintext and adds a typed query layer, an automatic entity graph, conflict-free merge, and provenance on every fact.

  • Agent-memory libraries (mem0, Letta, agentmemory). A vector store, a cloud API, or a framework you are locked into; memories are opaque, LLM-rewritten blobs with no provenance or audit. Mazarbul is local, four-layer, event-sourced, and every fact cites its source and is auditable.

  • Key-value or vector stores, ChatGPT / Claude built-in memory. Opaque, cloud-locked, no schema or relations or query or audit, siloed per product. Mazarbul is a system of record you own, query, time-travel, and move.

Mazarbul

Vector memory (mem0, ...)

Obsidian + git + agent

Built-in cloud memory

Runs fully local, no account

yes

partial

yes

no

You own the source of truth

signed event log

cloud / vector blobs

markdown files

vendor cloud

Provenance + audit per fact

yes

no

manual

no

Typed query + graph

graph + vector + FTS

vector (+opt. graph)

no

no

Conflict-free multi-device git

yes

n/a

overwrites

n/a

Time-travel (valid-time)

yes

no

no

no

MCP-native for any agent

yes

SDK / REST

via plugins

vendor-only

Shared encrypted team scope

yes

cloud tier

manual

no

The wedge, in one line: agents need both free text and structure, and the systems that combine them (GraphRAG, Zep) all live in the cloud. Mazarbul brings that combination to a single file you own, with provenance and git-native sync no one else offers.

Use with Claude Code and any MCP agent

maz connect claude-code               # register over MCP (also: claude-desktop, ...)
maz connect claude-code --capture --warm-start   # passive capture + session warm-start
maz connect                           # show the live detection table for every client

Once connected, Claude Code works from your Book, traversing the graph to connect facts rather than just retrieving text. The same memory answers a headless claude -p one-shot and a live interactive session, with no tool list and no prompts:

Two Claude Code sessions, headless and interactive, traversing the memory graph to answer who bears the Ring and who has betrayed the Fellowship

For Cursor, a custom agent, or any other MCP client, run the server directly:

maz mcp serve            # stdio (default)
maz mcp serve --http     # streamable HTTP at 127.0.0.1:7842
maz mcp serve --unix     # Unix socket

Connected agents get a clean tool surface: remember, recall, forget, relate, get, neighbors, relations, entities, query, createEntity, defineEntityKind, getContext, getEntityContext (a token-budgeted dossier for one entity), agentFeedback, and more. The humans on your team use the exact same data through maz on the command line or its TUI.

For humans: TUI, live watch, and the Agent Mirror

The same memory has rich interactive surfaces — no agent required:

maz self                       # the Agent Mirror: what Mazarbul knows about you
maz recall "the ring" --tui    # interactive master-detail recall browser (recall → get → neighbors)
maz doc browse                 # two-pane TUI over your markdown vault
maz watch                      # live dashboard: events, jobs, embedding, and sync

maz learns how it's used

This is the centerpiece of the Omnigraph-parity wave. Every time an agent hits a confusing result, a wrong answer, or a hard-won rule worth keeping, it can record that friction. Recurring friction auto-promotes a distilled one-liner into a ## Known gotchas & lessons section that is appended last to every new MCP session's instructions — so every connected agent starts with the evolved guidance, without any human curation step.

# Record a durable lesson from the CLI (agents use the agentFeedback MCP tool).
maz feedback record --category lesson --severity medium \
  --surface recall \
  --summary "recall missed an exact name" \
  --rule "prefer get when you already hold the exact name"

# See what is currently promoted into every session's instructions.
maz feedback gotchas

# Inspect the raw triage queue.
maz feedback list --category confusing

# Pin a cluster (always included, even if the cap fills up).
maz feedback pin "lesson|recall|prefer get exact name"

# Suppress a cluster from promotion.
maz feedback veto "lesson|recall|prefer get exact name"

# Edit the distilled rule text.
maz feedback edit "lesson|recall|prefer get exact name" --rule "use get for exact-name lookups"

# Export an allowlist-redacted diagnostic (safe to share; no user memory ever leaves).
maz feedback export --format md -o feedback.md

Promotion thresholds: a cluster promotes after 3 recurrences, or 2 when its highest observed severity is high. Pinned clusters are exempt from the 8-entry cap; vetoed clusters never appear. Every review appends an audited event — nothing is ever deleted. The export strips all user memory, principal IDs, cluster keys, and team scope: only {id, ts, category, severity, surface, summary, detail, keywords, version, activePreset} leaves. See agent-docs/feedback-loop.md for the full design.

Output formats and scripting

Every read verb honors --output (or the MAZ_OUTPUT env var):

maz recall "Frodo" --output json          # single JSON document
maz entities --kind person --output ndjson  # one JSON object per line (stream-friendly)
maz entities --kind person --output csv     # CSV with a header row (cut/awk/spreadsheet)
maz entities --kind person --output kv      # key: value lines, blank between records (grep-friendly)

Aliases: table = text, jsonl = ndjson. Set a persistent default in your Book config:

maz config set output.default_format json

The config knob sits between MAZ_OUTPUT and the TTY heuristic in the precedence chain, so scripts get JSON automatically while interactive sessions still get a table.

Documentation

A hosted documentation site is on the way.

Contributing

License

Mazarbul is licensed under the Apache License 2.0. See LICENSE for the full terms and NOTICE for attribution.

Available Tools

64 tools
addIdentifierA

Attach an identifier (an alias by default) to an EXISTING entity, appending an entityIdentifierAdded event so the resolver and vault wikilinks match the entity by that surface form. Use this after renaming an entity's displayName via updateEntity to retain the prior name: addIdentifier{entityUid, identifier:"Old Name", kind:"alias"}. createEntity only seeds identifiers at mint time; this adds them later. kind defaults to "alias"; pass email/username/phone/id or a snake_case domain type for other identifiers. Returns E_NOT_FOUND when the uid does not resolve and E_VALIDATION on an empty identifier or malformed kind.

Inputs: entityUid (required), identifier (required), kind. Returns: name, status

agentFeedbackA

Record durable feedback about using Mazarbul: a friction point (confusing|missing|wrong_result|slow|tool_error|suggestion) or a lesson you learned (a one-line rule). Give a category, severity, and one-line summary; optionally the surface (tool/CLI), detail, and a distilled rule. Recurring feedback auto-promotes into your per-session guidance (the user can pin/edit/veto). File DURABLE friction or rules, not one-off disagreements.

Inputs: summary (required), category (required), rule, scope, +5 more. Returns: status, clusterKey

cancelJobC

Cancel a tracked background job by its AIP resource name ("jobs/{uid}").

Inputs: name (required). Returns: name, state

captureExternalA

Index an external item you fetched from a live connector (Notion, Linear, Granola, Drive, GitHub) WITHOUT copying its body into maz. One call stores a pointer + YOUR summary + a freshness anchor; maz never fetches or holds the content. recall later returns the summary with an inline freshness verdict so you reuse it when fresh and re-fetch live when stale. The capture is UNTRUSTED (lineage connector:): facts land proposed, never superseding your own. Idempotent by contentHash within the connector's TTL. Pass status=deleted|access-revoked to tombstone an item you can no longer reach. Refuses project scope and ephemeral connectors (gmail/gcal/slack; read those live). recall FIRST before capturing, to avoid duplicates.

Inputs: uri (required), connector (required), sourceType (required), label, +10 more. Returns: action, freshness, episodeNames, sourceRefNames, +1 more

connectSourceA

Connect a source and run a bounded first backfill into the graph. Give a connector (local-git, claude-chats, or granola) and, for the file-based ones, repoPath (granola uses a stored API key instead); optionally scope (personal|team, default personal), dryRun (preview + count without writing), maxItems, and maxExtractionCalls. Ingested content is UNTRUSTED: facts land proposed and capped, never superseding your own. Returns a run report with itemsApplied/Skipped and a jobUid. Refuses project scope.

Inputs: connector (required), scope, dryRun, maxItems, +2 more. Returns: dryRun, jobUid, streams, connector, +3 more

contextCorrectA

Correct a wrong item the cold-start brief surfaced. Pass the item's id (a pin's contextPins/{uid}, or an entities/{uid} the brief showed) and the corrected text; the brief renders your text in its place. The correction is a NEW event, not an in-place edit — history is preserved and the latest correction wins. Returns the overlay's contextPins/{uid}.

Inputs: text (required), targetId (required), scope. Returns: name, status

contextPinA

Pin a free-text steering note to the top of the user's cold-start context brief. Use it when the user states a durable preference or constraint they want surfaced first every session (e.g. "I'm mid-migration off Postgres — don't suggest new Postgres features"). The note wins a budget slot before auto-surfaced documents and entities. Returns the pin's contextPins/{uid}; retire it with contextUnpin or override it with contextCorrect.

Inputs: text (required), scope, targetRef. Returns: name, status

contextUnpinA

Retire a steering pin or correction so it stops surfacing in the cold-start brief. Pass its contextPins/{uid} (or bare ULID). The row is tombstoned, not deleted — history is preserved and the retire converges across devices. Use when a pinned note or correction is no longer relevant.

Inputs: pin (required), scope. Returns: name, status

countA

Count entities matching an AIP-160 filter — the deterministic answer to "how many …". With groupBy, returns a per-value breakdown (e.g. people per status) instead of a single total. Same filter grammar as the entities tool. Scope: defaults to project+personal; pass scopes:["team"] to include team entities.

Inputs: kind, limit, filter, scopes, +1 more. Returns: count, groups

createEntityA

Mint a structured entity of a registered kind directly, bypassing LLM extraction — the write-side complement to relate. Use it when you already hold an entity as (kind, displayName) and need its entities/{uid} to assert a relation, without a remember() round-trip. Inputs: kind (a core kind or a registered extension kind — register first with defineEntityKind, check with introspect), displayName, optional confidence (default 1.0), identifiers (anchor the entity so the resolver attaches future mentions instead of duplicating), alternateNames, and properties (typed attributes validated against the kind's propertySchema). Deduplicates before minting: a matching identifier returns the existing entity (status reused); an existing same-name or near-duplicate of the same kind is NOT created (status duplicate_candidates) — inspect candidates, then reuse a uid, merge with mergeEntities, or retry with force=true to record a genuinely distinct entity that happens to share a name. On a plain create (status created) any advisory near-matches are still listed in candidates. Returns E_VALIDATION on a malformed kind, empty displayName, out-of-range confidence, or non-object properties.

Inputs: kind (required), displayName (required), force, scope, +4 more. Returns: uid, kind, name, status, +1 more

defineEntityKindA

Register a new entity kind in the dynamic-ontology registry — but first check whether an existing kind already covers the concept (introspect → entityKinds, or describeType). The built-in dedup check runs automatically: a near-identical kind returns status="reused" with the existing name so you avoid minting a synonym; a medium-similarity near-duplicate mints but records a SKOS closeMatch alias (response field closeMatch + similarity, internal URN maz:kind: added to sameAs). Because that dedup runs a semantic embedding pass over existing kinds, this call routinely takes a few seconds to return — that latency is expected, not a hang; do not abort or retry on a short timeout. Inputs: name (bare snake_case, no namespace), displayName, description (required for dedup), optional extends (parent kind — must be a core kind or an already-registered active kind; bare names resolve to their canonical registered form), sameAs (external vocabulary IRIs), propertySchema (JSON Schema for typed attributes). Appends an entityKindRegistered event; the dispatcher materialises it into entity_kinds and the render pipeline writes it to the git-synced ontology/ tree. Re-registering an existing user kind with force=true overwrites it. Attempting to modify a core kind, or extending an unknown/ambiguous parent, returns E_VALIDATION.

Inputs: name (required), description (required), displayName (required), force, +4 more. Returns: name, plan, status, warnings, +3 more

definePredicateA

Register a new predicate in the shared predicates vocabulary — but first call introspect to check existing predicates (works_at, member_of, etc.) so you don't mint a synonym. Inputs: predicate (snake_case), kind (functional for at-most-one-live-value, non-functional for multiple concurrent values), description, and optional typing: subjectKinds/objectKinds (domain/range — the entity kinds allowed on each end), sameAs (external-vocabulary IRIs), and propertySchema (a JSON Schema for the relation's attributes). Domain/range and attribute constraints are advisory by default and enforced only when [ontology] strict_domain_range is enabled. The predicate is immediately queryable via introspect and usable in relate calls. Re-registering an existing predicate updates its kind, description, domain/range, sameAs, and propertySchema and returns status=updated. Returns E_VALIDATION if the predicate name or propertySchema is malformed.

Inputs: kind (required), predicate (required), description (required), sameAs, +3 more. Returns: status, predicate

defineSchemaA

Register a JSON Schema document in the dynamic-ontology schema registry. Use this to attach validation schemas for custom entity-kind properties (schemaKind=entityKind:vehicle) or to define schemas for new event types. Inputs: schemaKind (bare camelCase or colon-namespaced, e.g. entityKind:deal), version (semver vX.Y.Z), definition (JSON Schema object). Core schema kinds (entity, episode, etc.) are protected and return E_VALIDATION. The schema is immediately usable for property validation via ValidateEntityProperties. Returns E_VALIDATION if the definition is not a JSON object or if schemaKind is a protected core kind.

Inputs: version (required), definition (required), schemaKind (required), preview. Returns: plan, status, version, warnings, +1 more

deleteEntityA

Hard-delete an entity by ULID: removes the entity and all its derived data (relations, facts, mentions, identifiers, citations) and detaches its graph node, appending an entityDeleted tombstone to the audit log. This is for unwanted or junk entities — to consolidate DUPLICATES without losing data use mergeEntities instead. Safe default: refuses with E_VALIDATION when the entity still has active relations (so a connected entity is never dropped by accident); pass cascade=true to tombstone those relations first and proceed. Returns E_NOT_FOUND when the uid is unknown.

Inputs: entityUid (required), reason, cascade. Returns: name, status, forgottenRelations

describeTypeA

Describe a single entity kind in full: displayName, description, parent (extends), child kinds, external-vocabulary aliases (sameAs), provenance lane, and how many entities currently carry it. The deep counterpart to introspect's cheap kind index — call it to confirm a kind's shape and reuse before minting a near-duplicate with defineEntityKind, or before createEntity. Accepts a canonical name (person, user:vehicle) or a bare local name (vehicle) that resolves to the user: kind when unambiguous. Returns E_NOT_FOUND with near-name suggestions when the kind is not registered.

Inputs: name (required). Returns: name, parent, sameAs, addedBy, +6 more

dismissInsightA

Dismiss a synthesized insight the user judges wrong or unhelpful. Appends a durable insightDismissed event (the source of truth) that flips the insight to a terminal 'dismissed' state - it drops out of hot recall and is never re-promoted by access. This is NOT a decay/demotion (which the system does on its own); it records an explicit user decision and survives a rebuild. Identify the insight by insights/{uid} or a bare uid. Returns the dismissed insight's resource name.

Inputs: name (required), reason, scopes. Returns: name, status

editDocumentA

Edit a document by exact string replacement (Claude-Code Edit semantics): oldString must match the current body exactly and be unique unless replaceAll. The result is ingested as a new revision (history kept; wikilink edges re-resolved; removed links forgotten) and the vault file refreshes. Use writeDocument to replace a whole body. Result counts (edges, unresolved) are whole-document snapshots after the edit.

Inputs: path (required), newString (required), oldString (required), scope, +1 more. Returns: file, name, path, edges, +8 more

entitiesA

List and filter entities by kind, name substring, and confidence, with pagination. LLM-free discovery surface: find an anchor here, then pivot into neighbors/relations. sortBy=recallCount returns the most-recalled entities (replaces listTopEntities). Spot a duplicate of the same real-world thing? Consolidate the pair with mergeEntities (lossless); remove a junk entity with deleteEntity.

Inputs: kind, limit, filter, offset, +6 more. Returns: entities

factA

Record a scalar fact — an attribute, state, or preference — about an entity as a (subject, stateKey, value) slot, bypassing LLM extraction. The fact-shaped counterpart to relate: relate records edges between entities, fact records a single entity's slots (e.g. state.task.status=pending). A later write to the same stateKey supersedes the prior value (kept as history). Read them back via get(entities/{uid}) for the current slots, or get(facts/{uid}) for one.

Inputs: value (required), subject (required), stateKey (required), scope, +3 more. Returns: name, status

forgetA

Forget an Episode, single Relation, or single Fact by ULID: appends a tombstone that removes derived state across the storage layers while preserving the JSONL audit trail. factUid hard-deletes a fact (state/preference) slot value — use retractFact to close a fact while keeping its history.

Inputs: reason, factUid, episodeUid, relationUid. Returns: name, status

getA

Fetch one record by AIP resource name — entities/{uid}, episodes/{uid}, relations/{uid}, facts/{uid}, insights/{uid}, or consolidatedMemories/{uid} — plus its provenance lineage. For an entity you may also pass a bare uid or a human display name (resolved case-insensitively, the same forms relations/neighbors accept). When a name is shared across kinds, a non-document entity deterministically wins over a same-named document — the passed-over document(s) are surfaced in shadowedDocuments as entities/{uid} you can fetch directly; pass kind to target a specific kind, or a vault path / entities/{uid} to address a document. A name that is ambiguous among non-document entities (or unknown) returns a pointed error naming the candidates. The structured, LLM-free way to follow any recall hit's name field. Returns a discriminated union tagged by type. An entity record returns the canonical node (uid, kind, displayName, confidence, resolutionStatus) AND its typed properties, external identifiers, and currently-open scalar facts. A relation record carries hydrated endpoints + validity. An episode carries its source text. An insight (type=insight) returns the synthesized statement, insightType, currentConfidence, state, synthesizedAt, and its sourceUids as entities/{uid} citations. A consolidated memory (type=consolidatedMemory) returns the compressed summary, memoryType, confidence, consolidatedAt, and its sourceUids as episodes/{uid} citations. Demoted insights (state='demoted') are still fetchable — get is not the hot-recall index.

Inputs: name (required), at, asOf, kind, +2 more. Returns: fact, type, facts, entity, +7 more

getCapacityA

Return per-storage-layer on-disk byte totals: event log, sqlite+fts, graph, vector index, embedding cache, plus free disk.

Inputs: no named parameters. Returns: onDisk

getContextA

Assemble a token-budgeted markdown brief of the user's working set — pinned documents, recently-updated documents, key entities, and (when you pass a query) the most relevant hits — for loading at the start of a session. Deterministic and fast (no LLM). The brief never exceeds budgetTokens; lower-priority content is dropped behind a visible marker. Prefer this over many small reads when you need to warm up context about the user.

Inputs: query, scopes, budgetTokens. Returns: budget, tokens, dropped, markdown, +1 more

getEntityContextA

Assemble a single token-budgeted markdown dossier for ONE entity, collapsing what otherwise takes five calls (get + relations + neighbors + recall + facts) into one card. The dossier carries a header (name, kind, entities/{uid}, resolution status), Connections (the entity's typed relations as direction-aware predicate fragments), What I know (its scalar facts), Mentioned in (recall hits naming it), and a counts footer. Pass entity as an entities/{uid} resource name, a bare uid, a display name (resolved case-insensitively), or self. Use at (RFC 3339) to time-slice the relations + facts to a past instant; the header is unchanged. The card never exceeds tokenBudget; lower-priority bullets are dropped behind a marker. An unknown entity returns E_NOT_FOUND; an ambiguous display name returns E_VALIDATION naming the candidates. Prefer this over many small reads when you need the full picture of one entity.

Inputs: entity (required), at, scopes, include, +1 more. Returns: budget, tokens, dropped, markdown, +1 more

getSourceRefA

Fetch one external-source provenance record (SourceRef) by AIP resource name sourceRefs/{uid}. A SourceRef records what a memory was derived from — the connector, stream, external id/url, content hash, and fetch time (W3C PROV wasDerivedFrom). Its provenance is SELF-ASSERTED and UNVERIFIED (trustState is always "unverified"): there is no cryptographic attestation of the external claim yet. Use recordSourceRef to create one.

Inputs: name (required), scopes. Returns: uid, name, scope, stream, +11 more

getUsageSnapshotA

Return the current usage snapshot: events written, recalls performed, embed-cache hit rate, recall latency percentiles.

Inputs: window. Returns: events, window, recalls, bytesIngested, +6 more

idleStatusA

Return current background-work counters: extraction queue depth, in-flight enrichment, in-flight embeddings. Use to poll whether the kernel has caught up after a burst of remember() calls, before calling recall() for a clean retrieval measurement.

Inputs: no named parameters. Returns: isIdle, vecInflight, enrichmentInflight, enrichmentQueueDepth

ingestSourceA

Ingest the delta from a previously connected source, resuming from its saved watermark (cheap incremental pull). Give a connector (local-git, claude-chats, or granola) and, for the file-based ones, repoPath (granola uses a stored API key instead); optionally scope (personal|team), dryRun, maxItems, and maxExtractionCalls. Idempotent: unchanged items are skipped by content hash. Returns a run report with a jobUid. Refuses project scope.

Inputs: connector (required), scope, dryRun, maxItems, +2 more. Returns: dryRun, jobUid, streams, connector, +3 more

introspectA

Return the ontology you navigate by: the registered relation predicates (edge vocabulary, with functional/non-functional semantics), the entity kinds present (node vocabulary with live counts, plus taxonomy metadata — displayName, description, provenance namespace, extends/parent hierarchy, sameAs external URIs — for kinds in the registry), a namespaces summary (core/user/extension: buckets), and the event types recorded. Custom kinds added at runtime appear under the user or extension: provenance namespace. Call once to learn the vocabulary before filtering neighbors/relations/entities. NOTE: this lists what has been registered or extracted, so it can include rarely- or never-populated predicates — e.g. a role/title is usually an attributes.role string on a works_at/founded edge rather than a populated has_role edge — so confirm a predicate is actually in use (via relations) before relying on it. LLM-free.

Inputs: no named parameters. Returns: views, eventTypes, namespaces, predicates, +1 more

lintDocumentsA

Run a read-only health check over the markdown vault: orphans (no graph edges), deadLinks (unresolved [[wikilinks]]), contradictions (contradicts edges), danglingEdges (live link to a deleted doc), nearDuplicates (pairs of docs whose chunk embeddings exceed cosine 0.92, non-blocking lint signal only), and nameCollisions (documents whose title shadows a non-document entity of the same display name — wikilink resolution silently favours the entity). Takes no arguments; scans the whole vault.

Inputs: no named parameters. Returns: orphans, deadLinks, danglingEdges, contradictions, +2 more

listDocumentsA

List vault documents, most-recently-updated first, filtered by pathPrefix, tag, and/or pinned. Bodies are omitted to stay lightweight; call readDocument for one document's full body and edges.

Inputs: tag, limit, pinned, pathPrefix. Returns: documents

listDupCandidatesA

List entity pairs the post-consume dedup sweep flagged as likely cross-device duplicates. Auto-merged strong-identifier pairs (same email / username) are not included — only advisory candidates that need human review. Call mergeEntities on a pair to consolidate; use maz review dups for the interactive CLI view.

Inputs: no named parameters. Returns: total, candidates

listInsightsA

List synthesized insights by lifecycle state - the Insight Inbox read surface. Defaults to the hot (live, recall-visible) insights, most-confident first, each carrying its statement, confidence, lifecycle state, and the entity source records it cites (as entities/{uid} citations plus a count). Pass state=demoted, state=dismissed, or state=all to review the rest. Pair with get(insights/{uid}) to inspect one, dismissInsight to dismiss one, and triggerReflection to synthesize more.

Inputs: limit, state, scopes. Returns: insights

listJobsA

Return the currently-tracked background jobs (running and recent history), optionally filtered by state.

Inputs: stateFilter. Returns: jobs

listPresetsA

List the presets currently active (steering this agent's operating instructions). Returns name, version, and description for each — read-only. Presets are installed via the maz preset install CLI, not by agents.

Returns: presets

listSourcesA

List the external source connectors available to ingest from (e.g. local-git) and the resume watermark of each source connected so far (connector, stream, items ingested, last advance time). Read-only.

Inputs: no named parameters. Returns: connectors, watermarks

mergeEntitiesA

Merge source entity into target: repoints all relations, facts, and mentions from source to target, then removes the source entity row. Append-only: an entityMerged event is written to the audit log. Returns E_VALIDATION when source and target are the same uid, E_NOT_FOUND when either uid is unknown.

Inputs: sourceEntityUid (required), targetEntityUid (required). Returns: name, status

neighborsA

Expand an entity's neighborhood up to 6 hops and return the hydrated neighbor entities plus the relations connecting them, each hop tagged direction=outgoing|incoming relative to the seed. LLM-free graph walk: pass a recall anchor as the seed and traverse the structure yourself. The DEFAULT view is point-in-time NOW: only edges valid now and not superseded; pass includeInactive=true for full history, or time-travel with at/asOf. Filter edges by predicate. The limit (default 50) caps total neighbors across all hops, so deep walks stay bounded.

Inputs: seed (required), at, asOf, depth, +4 more. Returns: neighbors

promoteRelationA

Promote a proposed relation to asserted: verify an untrusted connector-ingested fact and lift its trust quarantine. A fact extracted from an external source (Granola transcript, Claude-chats export) lands status=proposed — it surfaces in recall but is excluded from supersession until confirmed. Promoting it asserts it, so it then behaves like any user-authored edge. Idempotent: promoting an already-asserted edge is a no-op.

Inputs: name (required), scope. Returns: name, status, promoted

queryA

Run a read-only SQL SELECT over the curated views (v_entities, v_relations, v_facts) — the analytical escape hatch for questions the structured entities/count filters can't express. Single statement, SELECT/WITH only; writes are rejected and impossible. Run introspect for the view columns. Scope: results default to project+personal; pass scopes:["team"] to include team rows. The views are pre-filtered to the requested scopes before your SQL runs — no WHERE scope = … clause needed.

Inputs: sql (required), limit, scopes. Returns: rows, columns, rowCount, truncated

readDocumentA

Read one vault document by path or documentUid: its title, verbatim body, frontmatter, tags, its wikilink edges — links (what it references: mentions of entities, links_to other docs) and backlinks (what references it) — and observations (the - [category] text lines parsed from the body). Each observation is projected to a durable fact ON THIS DOCUMENT ENTITY, so query them with get(entities/{documentUid}) or maz fact get <documentUid>. A document is also an entity, so the returned document.name (entities/{uid}) pivots straight into neighbors/relations to walk the unified graph.

Inputs: path, documentUid. Returns: links, document, backlinks, observations, +1 more

recallA

Search long-term memory for facts matching a query — about the user OR any person, place, organization, or event in the graph. CALL THIS before answering anything that depends on stored context (names, roles, projects, history, people, places, decisions); Mazarbul persists across sessions and clients, your conversation context does not. It is a SEED-FINDER: ground answers on each hit's text and entities[] — feed an entity name into get/neighbors/relations for the authoritative structured facts — not on the raw rank. fusedScore is a blended relevance score where rank ORDER is the signal, not absolute magnitude (normalized to [0,1] under the default weighted fusion, or a small reciprocal-rank value under rrf), so read each hit's text rather than blindly taking hit[0]. A miss is cheap; a confident hallucination is not. Recall ALWAYS returns its best-ranked candidates even when nothing strongly matches, so low, flat scores across unrelated hits usually mean the subject is NOT in memory — confirm a name with entities/get before treating a hit as fact, and use relations/neighbors (not recall) for the AUTHORITATIVE list of what mentions or links a known entity. Pass compact: true, maxTokens, or both to shrink the returned payload when you only need seeds to traverse. Returns ranked hits with citable ULIDs.

Inputs: query (required), at, asOf, near, +16 more. Returns: hits, lanes, degraded

recordSourceRefA

Record where a memory came from: append an external-source provenance reference (SourceRef, W3C PROV wasDerivedFrom) for a subject record. Give the subject's uid, a sourceType (open taxonomy), and a dedupKey for idempotency; optionally a connector, stream, externalId, externalUrl, and contentHash. Returns the new SourceRef's resource name. Provenance is self-asserted and UNVERIFIED. Does not fetch the source.

Inputs: dedupKey (required), sourceType (required), subjectUid (required), scope, +6 more. Returns: name, status

referenceA

Mint-or-return an external_ref entity for a URI: a first-class local pointer to information held in another system (a GitHub issue, a Drive doc, a Granola transcript, a repo file). Returns the external_ref's resource name so you can relate(localEntity, has_primary_source, name) to record that a local record is grounded in it. Idempotent: the same URI in the same scope returns the same entity. Defaults to personal scope (local, not rendered to the shared project git tree); pass scope=project to share. Mazarbul does NOT fetch the URI — to make the referenced content searchable, fetch it with your own tools, remember() it, then reference() the URI and relate the two. Returns E_VALIDATION on a URI with no scheme or an unknown scope.

Inputs: uri (required), label, scope. Returns: uid, uri, name, scope, +1 more

relateA

Assert a structured (subject, predicate, object) relation directly. You are the extractor: when you see a relationship, record it here rather than relying on server-side extraction (off unless a chat model is configured). Pass source for provenance. Returns the new relation's resource name.

Inputs: object (required), subject (required), predicate (required), scope, +6 more. Returns: name, status

relateBatchA

Assert multiple (subject, predicate, object) relations in ONE atomic event-log append. All edges are validated before any write: a single invalid endpoint aborts the entire batch. Use this to seed a graph in one call instead of N sequential relate() calls. Returns the new relation resource names in input order.

Inputs: relations (required), source. Returns: count, names, status

relationsA

List an entity's typed relations (incoming + outgoing), each row tagged direction=outgoing|incoming relative to the queried entity so directional predicates (reports_to, manages) read unambiguously. Endpoint names are hydrated. LLM-free. The DEFAULT view is point-in-time NOW: only edges valid now and not superseded; pass includeInactive=true for expired/superseded history, or time-travel with at/asOf. Filter by predicate. Role/title is often carried as an attributes.role string on a works_at/founded edge rather than a separate has_role edge; each row's sourceEventUid links back to the originating episode. Pair with neighbors to walk further.

Inputs: entity (required), at, asOf, limit, +3 more. Returns: relations

rememberA

Persist a fact to the user's long-term memory. CALL THIS whenever the user tells you something about themselves, their work, their preferences, decisions, plans, or corrects a prior fact, even if you think you'll remember it within the current conversation. Mazarbul is the durable store; your own context is not. Pass the original sentence verbatim. remember stores and indexes the text for recall; entities and relations are extracted server-side only when a chat model is configured (usually not), so write the structure you see yourself with createEntity, relate, and fact.

Inputs: text (required), actor, scope, source, +3 more. Returns: name

retractFactA

Close the current value of a fact slot — the scalar counterpart to unrelate. Records that a fact STOPPED being true (a status that no longer holds, a preference that changed with no replacement) by retracting it: it drops out of current reads but its history is PRESERVED (unlike forget, which deletes the row). The slot then reads as EMPTY — retraction does NOT fall back to an earlier value. Identify the value by its facts/{uid} or by the (subject, stateKey) pair (which closes the slot's single open value). To set a different value instead, just write it with fact() — a later write supersedes the prior.

Inputs: fact, scopes, subject, stateKey. Returns: name, status, retractedAt

shareToTeamA

Re-publish a personal-scope record (entity, fact, or relation) to the team scope so all admitted team members can read it. The personal original is unchanged — both copies coexist as separate scope lenses. Requires admitted team membership (else E_PERMISSION). Entities are deduplicated against the team scope by exact name before minting; an existing match returns status=reused. Facts and relations remap their endpoint UIDs to the team-scope counterparts: for a bare fact/relation share, all referenced entities must already be in team scope (else E_VALIDATION); for a subtree share (withFacts/withRelations), relations whose object has no team counterpart are skipped (status=skipped, reason set) rather than appended with dangling references. Use withFacts/withRelations to share an entity subtree in one call.

Inputs: ref (required), withFacts, withRelations. Returns: shared, status

team_createA

Create the team scope (genesis): mints a fresh per-team data-encryption key, admits this device's principal as the genesis owner, and switches the team scope to encrypted envelope mode. Fails if a team already exists.

Inputs: remote. Returns: status, dekEpoch, genesisPrincipalUid

team_device_listA

List all devices enrolled under the local principal's identity, including revocation status. Each device entry shows its signing-key fingerprint (sigKeyId), optional label, create time, and whether it has been revoked.

Inputs: no named parameters. Returns: devices

team_device_revokeA

Revoke an enrolled device by its ULID. Appends a deviceRevoked event to the team scope. After revocation, any event authored by this device with a UID greater than the revocation event's UID is dropped on all peers (convergent fold). The revoker must be the device's own principal, or a team admin/owner.

Inputs: deviceId (required), reason. Returns: status, deviceId, eventUid, principalUid

team_grantA

Admit a principal to the team by wrapping the current team data-encryption key to their pasted x25519 public key. The grantee unwraps it on their next sync pull. Requires the caller to hold at least admin role. The optional role parameter sets the grantee's access level (default: member).

Inputs: joinKey (required), role, label. Returns: role, status, dekEpoch, grantedEpochs, +1 more

team_joinA

Point this device at an existing team's encrypted remote so it can sync the shared brain, WITHOUT creating a new team. Use this (not team_create) to join a team someone else created. After joining, run team_key and send the blob to an admitted member to be granted, then sync pull to bootstrap the team key.

Inputs: remote (required). Returns: status, nextSteps, remoteUrl

team_keyA

Show this device's team join request: its bound principal UID and base64 x25519 wrap public key. Send both to an admitted team member so they can grant you (maz team grant --principal --wrap-pubkey ). Read-only; neither value is secret.

Inputs: no named parameters. Returns: joinKey, principalUid, wrapPublicKey

team_membersA

List the admitted team members (the derived ACL): opaque principal UID, DEK epoch, wrap public key, and whether each is the genesis owner. Read-only and contains no display names or other PII.

Inputs: no named parameters. Returns: members

team_revokeA

Revoke a team member and forward re-key the team: appends the revocation, mints a fresh data-encryption key at the next epoch, and re-wraps it to every remaining member. Returns a checklist — you must separately remove the principal's git-host access, which Mazarbul cannot do.

Inputs: principalUid (required), reason. Returns: checklist, newDekEpoch, rewrappedTo, revokedPrincipalUid

team_role_setA

Change an admitted team member's access role (owner | admin | member | reader) without re-wrapping key material. Requires the caller to hold at least admin role; assigning admin or owner requires owner. The change is recorded as a teamRoleChanged event and converges identically on every peer.

Inputs: role (required), principalUid (required). Returns: role, status, eventUid, subjectPrincipalUid

unrelateA

End a relation as of a date — the temporal counterpart to relate. Records that a relationship STOPPED being true (someone left a job, a project ended) by closing the edge with a valid_until: it drops out of current reads but its history is PRESERVED (unlike forget, which deletes the edge). Identify the edge by its relations/{uid} or by the (subject, predicate, object) triple (which closes the single open match). Pass endedAt for when it ended (defaults to now); pass supersededBy when a newer relation replaces it.

Inputs: object, scopes, endedAt, subject, +3 more. Returns: name, status, validUntil

updateEntityA

Relabel an entity's kind and/or displayName by appending an entityUpdated event. Supply at least one of kind or displayName; omitting both is E_VALIDATION. Returns E_NOT_FOUND when the uid does not resolve. Only the supplied fields change; confidence, properties, identifiers, and coordinates are untouched.

Inputs: entityUid (required), kind, displayName. Returns: name, status

waitForIdleA

Block until the kernel finishes all background extraction, resolution, and embedding work (or the timeout expires). Use between a burst of remember() calls and a benchmark recall() so the recall measures retrieval latency only, not the tail of ingestion. Cheap when the kernel is already idle.

Inputs: timeoutSeconds. Returns: isIdle, timedOut, elapsedMs, vecInflight, +1 more

writeDocumentA

Create or replace a markdown document at path with body (stored verbatim, event-sourced — full history is kept). [[Wikilinks]] in the body resolve to canonical entities and other documents as graph edges; dangling links reconcile automatically when their target appears. Optional title/pinned/tags/frontmatter synthesize a YAML frontmatter block when the body has none. Frontmatter about: <name|entities/{uid}> records the document's primary subject as a high-confidence describes edge (distinct from body [[wikilinks]], which are mentions); resolve it by uid where you can, since a renamed subject keeps the link. Frontmatter canonical: true lets this document win name resolution over a same-named non-document entity, so a later-created entity cannot silently steal the name. The document materializes as an editable file in the vault. Idempotent: rewriting identical content is a no-op. scope picks who sees the document (personal by default; team requires membership, else E_PERMISSION) and is fixed at creation — the same path in a different scope is a separate document. Result counts (edges, unresolved, reconciled) are whole-document snapshots after the write, not deltas. A non-fatal warnings field appears when the title shadows a same-named non-document entity.

Inputs: body (required), path (required), tags, scope, +3 more. Returns: file, name, path, edges, +8 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 64 tools

    Disambiguation3/5

    Most tools target distinct resources or lifecycle steps, and the long descriptions carefully distinguish read/write/close semantics (fact vs relate, forget vs retractFact vs unrelate). However, several clusters overlap enough to require careful reading: captureExternal/recordSourceRef/reference/connectSource/ingestSource/getSourceRef for provenance, and idleStatus/waitForIdle/getUsageSnapshot/getCapacity/listJobs for observability. Retrieval surfaces (recall, get, entities, query, getContext, getEntityContext) are differentiated but easy to misselect without the descriptions.

    Naming Consistency2/5

    The set mixes camelCase verbs (listPresets, getEntityContext, defineEntityKind), bare verb names (get, fact, relate, query, remember, forget, reference), and a snake_case team_* block (team_create, team_device_revoke, team_role_set). The team_ namespace is a readable exception, but over 64 tools the overall convention is inconsistent. Readability is preserved only because most names are still self-describing.

    Tool Count2/5

    64 tools is very heavy for any single MCP surface, even a broad memory/graph kernel covering entities, documents, ontology, provenance, team sync, jobs, and observability. Each subsystem has a plausible reason to exist, but the total surface is large enough to burden tool selection and context. It sits well above the 25+ threshold for 'too many' rather than being an extreme 50+ mismatch only because the stated domain is genuinely wide.

    Completeness4/5

    The surface covers a lot: entity CRUD and merge, relation/fact creation, retraction, forgetting, document read/write/edit/lint, ontology definition and introspection, insights, jobs, sources, provenance, team ACLs, and context briefs. Only minor lifecycle gaps are apparent, such as no explicit document delete tool and no direct relation update beyond unrelate/re-relate. These are workable for agents but leave a few dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-first, multi-user shared memory for AI agents with semantic search, offline support, and team synchronization.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Local-first memory engine for AI-agent teams: private/team/project ACL, associative recall, and federated sync across nodes. One SQLite file, no LLM required.
      12
      9
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-first memory for AI agents with evidence-backed recall, deterministic trust verdicts, self-inspection, and a tamper-evident audit history.
      Apache 2.0