---
title: "Humans and agents on a shared core"
description: "One knowledge base, equally open to people and AI agents: an agent's edits are versioned, bounded by access and signed with provenance."
---

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

```mermaid
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](/docs/concepts/versioning/).
- **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](/docs/concepts/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.

> [!note] 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](/docs/agents/); the first practical step is [Connect an agent](/docs/getting-started/connect-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](/docs/agents/security/).