Mazarbul

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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 <uid> --wrap-pubkey <key>). Read-only; neither value is secret.

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.

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.

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.

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.

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.

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.

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.