# Stores

```ts
// stores/history.ts
import { store } from "@praecise/harness";

export default store({ of: "sql" });
```

That is a working store. It keeps a file under `.praecise/` and needs nothing
installed. Give it a `url`, or a `credential` naming the environment variable
that holds one, when it should live somewhere else — a `postgres://` url moves it
to a server, and nothing above changes.

The built-in backend's text search rides on the FTS5 module of Node's bundled
SQLite. Whether that module is present is a property of how your Node was BUILT,
not of its version number — the Node 22 this was last checked against has it, and
a build without it raises `no such module: fts5` while everything else about the
store keeps working. If search matters, check rather than assume:

```sh
node -e 'new (require("node:sqlite").DatabaseSync)(":memory:").exec("CREATE VIRTUAL TABLE t USING fts5(x)")'
```

Four verbs work on every store, whichever family you declared:

```ts
const history = await app.store("history");

await history.remember({ text: "customer asked about order 4021", scope: "acme" });

await history.recall("order 4021", { scope: "acme" });   // relevant, recent counting for more
await history.search("4021");                             // contains these terms, whatever its age
await history.history({ limit: 50 });                     // newest first
await history.forget({ scope: "acme" });                  // and how many went
```

`recall` and `search` are different questions. `search` is a lookup and does not
care how old something is. `recall` is a judgement, and a judgement decays —
something said this morning is more likely to be what you meant than the same
sentence from a year ago.

None of the four composes a query, which is the point: an agent asking to recall
something has no string to compose badly. Your own SQL is a separate door:

```ts
await history.query("SELECT total FROM invoices WHERE account = ?", ["acme"]);
```

A store declared `of: "vector"` compares vectors you supply, and falls back to
text when you do not:

```ts
await history.remember({ text: "…", vector: embedding });
await history.recall(embedding, { limit: 5 });
```

Embeddings are supplied rather than derived, unless an endpoint says what it
embeds with. Name an `embeds` model on an endpoint in `models` and an agent that
remembers into a vector store has each exchange embedded as it is kept and is
recalled by meaning. If the embedding cannot be had, recall falls back to text.
`App.load({ embedder })` takes your own function instead.

Asked with both, a store answers both ways and joins the two orders by
reciprocal rank:

```ts
await history.recall({ text: "order 4021", vector: embedding }, { scope: "acme" });
```

An agent that remembers into a vector store is recalled this way. A reranker
scores what was found a second time, reading the question and each candidate
together: name a `reranks` model on an endpoint (sent to `{url}/rerank`), or pass
`App.load({ reranker: async (query, documents) => scores })`. `{ rerank: false }`
leaves it out of one question.

## Typed records

A store may say what a record in it looks like, with any Standard Schema
validator:

```ts
// stores/tickets.ts
export default store({ of: "document", schema: Ticket });
```

Everything `remember` is given is checked first. A batch with anything wrong in
it is refused whole, with a `SchemaError` whose `issues` name each row, path and
message, and what is kept is what the validator returned. `RecordOf<typeof spec>`
is the record's type. It is a check on the way in and nothing more; values, facts
and series are not checked against it.

## Values, facts and series

Text to recall is one shape of data. A store also keeps three others, on every
backend, with nothing more to declare or install:

```ts
const kept = await app.store("history");

// a value under a name, in a namespace, with an optional lifetime in seconds
await kept.values.put(["users", "ada"], "theme", { dark: true }, { ttl: 3600 });
await kept.values.get(["users", "ada"], "theme");
await kept.values.list(["users", "ada"]);
await kept.values.delete(["users", "ada"], "theme");

// how two things are related, and when that was true
const id = await kept.facts.relate("ada", "works_at", "acme", { validFrom, source: "hr-export", confidence: 0.9 });
await kept.facts.unrelate(id, { at });                       // closed, never deleted
await kept.facts.facts({ subject: "ada", asOf });            // what was true then
await kept.facts.neighbors("ada", { direction: "both", depth: 2 });

// readings in order of time
await kept.series.append("boiler/temp", [{ at, value: 61.5, tags: { unit: "Cel" } }]);
await kept.series.range("boiler/temp", { from, to, bucket: 60_000, aggregate: "mean" });
await kept.series.last("boiler/temp");
```

A value is replaced when written again. A fact said twice is one fact, and one that
stops being true keeps its place in the record: `asOf` answers with what was true
at a moment, and `asOf: "ever"` with everything that was ever believed. A reading
sent twice for the same moment is one reading. None of the three turns up when an
agent recalls something, because each is kept under a scope of its own.

They are verbs over the operations every backend already implements, so a driver
you bring has all of them once it passes `conform`. What that costs is stated: on
a backend that offers nothing more, a walk over facts and an aggregate over a
series read the rows involved and work the answer out in this process. That is the
right trade for what an agent keeps and the wrong one for a warehouse, which is
what `query()` is for.

A backend may do some of it itself, and says which in `capabilities.faster`:
`walk`, `buckets`, `ids`, `validity`. The file and Postgres backends walk facts
with a recursive query and aggregate a series in the database, Postgres using
`time_bucket` where TimescaleDB is found. On PostgreSQL 18 ids are made by the
server (`uuidv7()`), and where `btree_gist` is installed a fact's validity is
held under a key that refuses overlap, so `facts.relate` throws on a fact that
overlaps one already there. `conform` holds each of these to the answer worked
out in this process.

A `postgres://` url takes two settings of its own. `sslmode` is `disable`,
`prefer` (the default), `require` or `verify-full`, which also checks the
certificate. `max_protocol_version` is `3.0` (the default), `3.2` or `latest`:
3.2 arrived with PostgreSQL 18, is asked for only when the url says so, and a
server that does not speak it answers with the version it does, which the
connection then uses. The version a
connection settled on is in the store's `capabilities.detail`.

There is no ORM, and that is a decision rather than a gap. A layer mapping tables to
classes buys type safety for code a person writes; an agent's access to data is
safe because of the role its connection holds and because every value is bound, not
because of a type. For a table of your own, `query()` takes the SQL.

## Which families are served

`of` takes five families. What ships serves four of them, and it serves them
through one shape: a table of text, json metadata, a time, and an optional
vector.

| | |
|---|---|
| `sql` | served — it is a table, and `query` is its own SQL |
| `document` | served — metadata is `jsonb` on a server, JSON on a file |
| `timeseries` | served — ordered and ranged by time, and partitioned by it where TimescaleDB is installed |
| `vector` | served — ordered by pgvector or sqlite-vec where those are installed, compared in this process where they are not |
| `graph` | **not served as an engine** — relationships are kept and walked through `facts` on any store; a graph database is a backend you bring |

A family the backend cannot honour is refused when the store is opened, and the
refusal names what is served and what to do instead. It used to be accepted:
`of: "graph"` against a `postgres://` url got the same table of text as
everything else, and nothing anywhere said so. `of` is still declarative where a
driver *can* honour it — nothing changes about the four verbs — but it is no
longer a word that only reaches a prompt.

Which path a store is actually on is a question with an answer:

```ts
const kept = await app.store("history");

kept.capabilities.vectorSearch;  // "index" — the database orders them
                                 // "scan"  — every vector is read and compared here
kept.capabilities.detail;        // why that one, and what would change it
```

A fallback that is a hundred times slower and completely invisible is the kind
of thing that gets discovered as a latency graph a year later, so it is not
invisible.

## What an extension costs the person installing it

Nothing here requires one, and each is worth a different amount of trouble.

| | |
|---|---|
| **pgvector** | `CREATE EXTENSION vector` — one statement, no restart, no config edit. A `vector` store then keeps embeddings in a real `vector(n)` column with an HNSW index, and `ORDER BY … <=> …` happens in the database. Declare `dimensions`; a column with no width cannot be indexed. |
| **TimescaleDB** | `shared_preload_libraries = 'timescaledb'` in `postgresql.conf`, then **a restart** — the one extension here that costs downtime. A `timeseries` store is then a hypertable in weekly chunks. Only `create_hypertable` is used, which is in the Apache-2.0 subset; compression, continuous aggregates, retention policies and the job scheduler are the source-available half and are deliberately not touched. |
| **sqlite-vec** | Build or download the extension, then name the file in `PRAECISE_SQLITE_EXTENSION`. Off unless that variable is set: loading one runs somebody else's machine code inside the process holding your data, which is a decision for whoever is deploying, not for a framework guessing from a url. |
| **Apache AGE** | `CREATE EXTENSION age`, then `LOAD 'age'` and a `search_path` in **every session**. Nothing here uses it, and a graph store is refused rather than pretended at. |

An existing table is never migrated underneath you. A Postgres store that
already keeps its vectors as `bytea` goes on comparing them here even once the
extension is installed, and says so in `detail` — reading a column that no
longer holds your vectors would not be faster, it would be empty.

All of it is reachable through `query()` right now, whether or not anything
above knows the extension exists:

```ts
await kept.query("SELECT id FROM praecise_items ORDER BY vector <=> $1 LIMIT 5", [asked]);
await kept.query(`SELECT time_bucket('1 day', to_timestamp(at / 1000)) AS day, count(*)
                  FROM praecise_items GROUP BY day ORDER BY day DESC`);
await kept.query("SELECT * FROM cypher('g', $$ MATCH (a)-[:KNOWS]->(b) RETURN b $$) AS (b agtype)");
```

That door is the author's, not the agent's, and it is open before any of this
is.

## What an agent remembers

`memory: true` gives an agent four things, and they are kept apart on purpose:

| | What it is | Who writes it | How the agent meets it |
| --- | --- | --- | --- |
| The record | Every exchange: what was asked, what was answered | The runtime | A few that share words with the question are shown beside it; the rest it searches |
| Working notes | What the agent chose to write down while it worked | The agent, with `write_note` | It searches them |
| Subject pages | One page per thing it keeps coming back to, gathered from the record and the notes | The reflect pass | It searches and reads them |
| What it carries | A short list of facts and procedures | A person, by accepting a proposal | Placed in front of it on every request |

Only the last row changes what an agent is told, and only a person changes it. The
other three are things the agent looks through with `search_memory` and
`read_memory`, and they are labelled with where they came from: its own and
unconfirmed, from a person, or from outside the app. An exchange is kept as
`external` when anything the app does not trust was read while answering, and
whatever is later drawn from it is held to that.

Words are found in whatever script the text is written in, so recall works the
same for text that is not in Latin letters.

An agent can remember into a store instead of into files, and then all four of
those are in the store: the record and the notes as rows its index searches, the
pages and what it carries as documents beside them. Nothing of its memory is on
the machine's disk, so several machines serving one app against one database have
one memory.

```ts
export default agent({
  role: "Answers customer questions about orders.",
  memory: { store: "history" },
});
```

Each agent is its own scope, so one store holds every agent's memory without any
of them seeing another's. `store: "history"` in `praecise.config.ts` makes that the
store for every agent that asks for memory without naming one. A store an agent
remembers into holds records of the framework's own shape, so it is declared
without a `schema`; one with a schema is refused at load.

## Reading the record back

```sh
praecise memory support            # what it carries, and any proposal waiting
praecise memory support --reflect  # read the record: propose changes, file what is new onto pages
praecise memory support --accept   # adopt what was proposed, or `--accept 0,2` for those positions
praecise memory support --reject   # discard the proposal; the record is untouched
praecise memory support --retire <id>   # stop carrying one entry
praecise memory support --record   # the exchanges it kept, with their ids
praecise memory support --notes    # the working notes it wrote
praecise memory support --pages    # its subject pages; `--page <name>` shows one
praecise memory support --redact <id> --note "sent in error"
```

`--reflect` asks a model to read the record and the working notes against what the
agent carries now. It proposes facts and procedures to start carrying, each naming
the exchanges or notes it was drawn from, and it proposes closing or replacing a
carried entry where the record shows it has changed. Nothing it proposes takes
effect until `--accept`.

What is carried accumulates: an entry adopted last month is still carried after the
exchanges it came from have aged out of the record. A replaced or retired entry is
closed with the time, not deleted. Where a proposed entry would replace a carried
one, the one from the source of higher authority stands, and between equals the
later one; that is compared as values and never asked of a model. An agent carries
at most 48 entries, because every one is read on every request.

The same pass files what is new in the record onto subject pages. Each page is
written by a request of its own that is shown that page and the entries filed on
it, and a page changed by someone else in the meantime is left as it is. Pages
need nobody's agreement because they are only ever found and read.

The pass takes the agent's memory to itself while it runs: a second one for the same
agent, from this process or from another machine on the same store, is refused
(`AlreadyReflecting`) until the first is done.

To have the record read back on a schedule while the app is served:

```ts
export default agent({
  role: "Answers customer questions about orders.",
  memory: { reflect: { cron: "0 3 * * *" } },
});
```

`praecise dev` and `serve()` start that schedule. An app made with `App.load` or
`createApp` and served some other way starts it with one call, `app.tend()`. Where
several processes serve one app each may call it: a tick is read back once.

`--redact` takes one exchange or working note back: the record still shows that
something happened and when, with the note where the words were (`taken back` when
none is given), and the agent does not answer from it again. From code these are
`app.reflect`, `app.pending`, `app.accept`, `app.reject`, `app.retire`,
`app.learned`, `app.carried`, `app.recorded`, `app.jotted`, `app.jot`, `app.filed`,
`app.page`, `app.redact` and `app.clearMemory`.

## What memory is worth

```sh
praecise eval support --memory
```

runs one suite twice. First as always: every case asked as though nothing had been
asked before. Then with a memory that starts empty, the cases asked in the order
they are written, each able to use what the ones before it left. It reports both
and the difference. The second run keeps its memory under a name of its own and
removes it afterwards, so the agent's real memory is neither read nor written. A
suite measures this only where its cases build on one another. From code:
`app.evaluateMemory(suite)`.

## Bringing a backend

Four backends ship: a file, a Postgres server spoken to over its own wire
protocol, Redis or Valkey spoken to the same way, and one that keeps nothing past
the process — `url: "memory:"`, for an example or a test that should leave
nothing behind. None costs a dependency.

```ts
// stores/cache.ts
export default store({ of: "vector", url: "redis://cache:6379/0?prefix=app", dimensions: 1024 });
```

A `redis://`, `rediss://`, `valkey://` or `valkeys://` url is spoken to in RESP3,
falling back to RESP2; `rediss` and `valkeys` are the same over TLS. The path is
the database number, and `?prefix=` is what every key starts with (`praecise` by
default). Vector sets, time series and JSON are used where the server has them.
There is no text index, so `search` reads a scope and compares; `sql` and `graph`
are not served; and `query()` takes a command, not SQL.

Anything else is a `Driver` your app hands over, matched to a store by the scheme
of its url. A driver's connection keeps, lists, matches, drops and redacts rows,
and `add`s one only if nothing is kept under its id, which the backend has to
decide in one step: locks, leases and document revisions are made from it.

```ts
const app = await App.load({ drivers: [myDriver] });
```

A driver implements named operations — keep these, list that window, match these
terms, drop this scope — not a SQL string. Everything above it is written once
and every backend gets it, and there is no query language between a model and
your data for either of them to get wrong.

Four that are worth the afternoon, one per family this does not serve well or at
all. Each speaks HTTP, so a driver is a `fetch` and the six operations above it:

| | |
|---|---|
| **Qdrant** for `vector` | Apache-2.0. Named vectors, payload filters and a filtered search that stays exact — which is the thing an approximate index gives up when a window narrows. |
| **Neo4j Community** for `graph` | Its Query API is plain HTTP: `POST /db/neo4j/query/v2`, Cypher in the body, Basic auth. The server is GPLv3; speaking HTTP to a server creates no obligation for the thing doing the speaking, which is what makes this reachable without a licence conversation. |
| **CouchDB** for `document` | Apache-2.0, and HTTP is its native interface rather than a gateway to it. Mango selectors do the narrowing. |
| **ClickHouse** for `timeseries` | Apache-2.0. Where a hypertable stops being enough and the question turns into an aggregate over a billion rows. |

None of them is a dependency here, and none of them is endorsed by anything but
the fit. `conform` grades whichever you write exactly as harshly as the ones
that ship.

Most of what a store promises is not in the type. A redacted row keeps its place
and its timestamp; clearing what it said also clears the vector it could still be
found by; a negative limit means the whole window; handing a row back does not
hand over the row itself. A driver can satisfy the compiler completely and get
every one of those wrong, and nothing would say so until an agent recalled
something that was meant to have been taken back. So ask it:

```ts
import { conform, conformanceReport } from "@praecise/harness";

console.log(conformanceReport(await conform(myDriver, { url: "…" })));
```

It answers with a line per promise, says which it did not check and why, and
does not grade your backend any more gently than the ones that ship.
