# Renor — how it works (agent plane)

Renor gives AI tools and agents durable memory: context told once is available again when it is
relevant, instead of being repeated every session. Everything below is read off the shipped code
(`engine/src/mvp/server.ts`, `engine/docs/user/WHAT-YOU-CAN-DO.md`); the human version, with real tool
output, is at `https://renor.cloud/how-it-works`.

## The three stages

1. **Capture** — an agent or a human writes a fact, a note or a decision (`remember`, `save_memory`,
   `remember_note` on the hosted surface). Nothing is saved unless an agent or a person asks.
2. **Organize** — notes are indexed into chunks, full-text search, entities and embedding vectors;
   facts are kept as a ledger of subject–predicate–object values, where a newer value supersedes an
   older one and the older one stays in history.
3. **Recall** — before substantive work an agent calls `get_context` with the current request and
   receives current facts first, then relevant notes, matched by meaning and by words where the
   workspace has semantic search and by exact words otherwise (the reply's `retrieval` field says
   `hybrid` or `keyword`), cut to `max_tokens` (default 800, at most 4000).

## What is stored

- A **fact**: subject, predicate, value and the sentence the user said, in an append-only markdown
  ledger (`System/Memory Events Ledger.md`). A **note**: the user's words, whole, in a markdown file
  under the day it was saved. The SQLite index is derived and can be rebuilt by replaying the ledger.
- Each workspace has its own memory directory, index and server process, under its own OS account. Every hosted workspace has semantic search on (checked 2026-10-07); one without an embedding provider would match exact words only.
- `remember({statement})` stores a note (max 4000 characters; longer is refused, never cut). Add
  `subject`, `predicate` and `object` together only for a value that stays current until it changes.

## Corrections keep history

Saving the same subject, predicate and scope again replaces the current value and closes the old one:

    remember {subject: Fjord, predicate: database, object: PostgreSQL}  -> action "store"
    remember {subject: Fjord, predicate: database, object: SQLite}      -> action "supersede", closed PostgreSQL
    get_context("what database does Fjord use?")                        -> facts: Fjord database SQLite
    retrieve_memory {subject: Fjord, include_history: true}             -> SQLite (current), PostgreSQL (validTo set)
    retrieve_memory {subject: Fjord, as_of: <ISO date>}                 -> the value current at that date

Dependency, stated plainly: replacement happens only when the agent saves the new value with the same
subject, predicate and scope, spelled the same way. Two plain notes that disagree are both kept; Renor
does not read sentences to detect contradiction. It reports `possibleDuplicates` for near-identical
names or other scopes and merges nothing. `retire_memory` removes one memory from recall reversibly
(`restore_memory` undoes it); it is not erasure.

## Several agents, one workspace

Every MCP client the owner signs in reads and writes the same workspace. Each memory records a
`source` name (the saving app or agent; self-reported by the client, not authenticated). `scope`
(`project:<slug>`) separates projects but is not a permission: an unscoped read sees every scope.
There are no per-agent permissions and no sharing between people.

## Export, availability, latency

- `export_memory` returns the fact ledger (superseded values included). Notes are not in it; read
  them with `memory_map` and `read_memory`. Import: `preview_import`, `apply_import`, `undo_import`.
- A call to an unavailable workspace fails (503 with `Retry-After`, or 502 for an unknown workspace)
  and writes nothing; nothing is queued or replayed. An idle workspace stops and is started again by its next
  call (on-demand sleep is on in production, checked 2026-10-07; a few seconds).
- Measured 2026-10-06 (`data/renor-engine-latency/report.md`): a hosted `get_context` is about 430–500
  ms at the median, about 20 ms of it the engine. One day, one location, no guarantee.

## What is stored where, and what you control

- Memory belongs to the account that created it. A per-tenant MCP host rejects a platform connect
  token, which is why Renor hands out exactly one MCP URL: `https://mcp.renor.cloud/mcp`.
- Not built: self-hosting, one download of facts and notes together, self-serve permanent deletion,
  per-agent permissions, a documented REST API for memory.

## Where the rest of it lives

- Capability detail for connected clients: `https://renor.cloud/agents.md`
- Security and data: `https://renor.cloud/security`
- Evidence and results (including rejected changes): `https://renor.cloud/research`
- Plans and limits: `https://renor.cloud/pricing`
- Operating principles: `https://renor.cloud/culture`

This file mirrors the shipped architecture and the hosted tool registry
(`engine/docs/architecture/MCP-TOOL-SURFACES.md`, `engine/src/mvp/server.ts`). It is not a
performance claim: current results are published on the research page with their methodology.