Skip to content
BezialBezial

Quickstart

Bezial is one engine behind three call surfaces. The fastest way to feel it is the in-process TypeScript library; the same verbs are available over HTTP and MCP, and from Python.

Add and recall (TypeScript)

Section titled “Add and recall (TypeScript)”

BezialEngine is the server-side engine. Bind it to a principal (the caller’s identity) with .as(), and you get the full verb set with the acting identity implicit.

import { BezialEngine } from '@bezial/sdk';


const engine = new BezialEngine({ rootDir: './memory' });
const alice = engine.as({ id: 'alice' });   // the acting principal


// The only write path is a file: add() appends to Alice's dated note.
await alice.add('team', 'Alice switched from Notion to Obsidian in June 2026.');


// Recall reflects the write immediately (read-your-writes), with citations.
const now = await alice.recall('team', 'What note-taking app does Alice use?');
//   -> facts citing the source note; now.facts[0].object === 'Obsidian'


// Ask the memory as it was believed on a past date (bi-temporal as-of).
const then = await alice.recall('team', 'note-taking app?', {
  asOf: Date.parse('2026-05-01'),
});
//   -> the earlier belief, if any, as of that instant

What the calls do

Section titled “What the calls do”
Call What happens
new BezialEngine({ rootDir }) Opens the file-is-truth engine over a local store. Pass permissions: 'acl' to enforce the ACL model.
engine.as({ id }) Binds the engine to a principal, returning the identity-implicit client.
add(space, text) Appends text to the caller’s dated author-log note (<id>/<date>.md) and derives the changed section.
recall(space, query) Permission-filtered hybrid recall over the fact graph. Returns the R3 shape: cited, bi-temporal, confidence-scored facts.
recall(space, query, { asOf }) Recall the graph as it was believed at an instant.
recall(space, query, { synthesize: true }) Also returns a written answer over the filtered facts.
pin / forget / restoreFact Curate the derived memory - see Selective forgetting.

The recall() result is { facts, answer? }. Each fact carries a citation (path + version + section + line range), validTime, recordedTime, and confidence. See Recall for the full shape.

The Markdown is the truth

Section titled “The Markdown is the truth”

Nothing above is stored in an opaque database. add() and write() produce plain Markdown documents, versioned in the object store; the graph is a derived index over them that can be deleted and rebuilt at any time. That is what makes memory inspectable and editable: to fix a wrong memory, edit its source note with write() and the graph re-derives just that section.

// Write a document explicitly (last-writer-wins), then read it back.
await alice.write('team', 'alice/preferences.md', '# Preferences\n\nEditor: Obsidian.\n');
const doc = await alice.read('team', 'alice/preferences.md');

You can browse both views of the derived graph - the file map and the fact graph, with an as-of time slider - in the interactive viewer.

Reach the same engine another way

Section titled “Reach the same engine another way”
  • Python - the bezial package: the HTTP client at parity with TypeScript, plus a first-class in-process reference of the security-critical recall path.
  • HTTP / REST - a language-agnostic API over the same engine; authenticate with a Bearer key and call every verb.
  • MCP - any agent gets Bezial as a tool with zero glue.

Next steps

Section titled “Next steps”