Mazarbul

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.

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.

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

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:<name>): 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.

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.

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}.

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.

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.

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.

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.

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:<name> 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

List a document's wikilink edges without its body: `backlinks` (notes/entities that reference it) and `links` (what it references). The fast way to map a note's place in the graph. Identify the document by `path` or `documentUid`.

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

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.

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.

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.

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

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.

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.

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:<name> buckets), and the event types recorded. Custom kinds added at runtime appear under the user or extension:<name> 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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.