Humans and agents on a shared core

Notarium's core claim: the same knowledge base is equally available to humans and AI agents. A human works through the web interface (REST), an agent through the built-in MCP endpoint, and both see the same graph of notes on top of one portable core. This isn't a bolted-on "bot mode" on the side — it's feature parity by design.

One core, many transports

The architecture rests on a single principle: domain logic lives in one core, and transports only adapt access to it.

flowchart LR
  human([Human]) -->|REST · web editor| core
  agent([AI agent]) -->|MCP · POST /mcp| core
  core[Notarium core] --> files[(Markdown files)]

The core always decides, not the transport. So a note created by an agent travels exactly the same path as an edit from the editor: it's written to the same .md file, versioned in the log, bounded by the same access, and given a provenance record.

What "parity" means

An agent's edit and a human's edit are indistinguishable in how they're processed:

Versioning. Every edit is a revision in the log, tied to a notarium-id. See Version history.
Scope. An agent's token grants no more than the principal's membership: a read-only token can't even see the write tools. See Access model.
Provenance. Every revision shows where the edit came from: a human (user:<name>), a specific agent (pat:<name>:<id>), or an external file editor. Who edited what, and how, is always transparent.

Provenance, not anonymity

An agent's edits don't dissolve into a shared history. You can always open a note and see that this particular line was added by a specific agent under a specific token — and roll it back if you need to.

How an agent works

An agent reaches the knowledge base through a single endpoint, POST /mcp — a narrow set of 21 ready-made commands (create a note, recall context, search, write memory), not low-level storage operations. The tools express intent, while the system enforces placement and note class: the agent addresses a project by name but does not choose the space or the note class (a guard against mistakes).

The typical way in is a start_session call: the agent gets a profile, a list of its projects, and relevant context. Connecting and the full toolset are covered in Agents and MCP; the first practical step is Connect an agent.

Boundaries drawn deliberately

A shared core doesn't mean the agent can do everything:

An agent has no irreversible delete. Overwrite, yes (it's reversible through the log); permanent deletion of containers, no.
No cross-space operations. An agent works strictly within the spaces it can reach.
The tools have no channel to the outside world, and untrusted content is never mixed into their descriptions — this breaks the chain of "private data × untrusted input × an outbound path."
Notarium is deliberately not an E2EE product: a smart server needs to see content in order to provide search, semantics, and agents. Privacy comes from self-hosting and owning your files, not from end-to-end encryption.

More on protecting the agent perimeter: Security and visibility.