Praecise Harness v1.1.0 Get started

Documentation · Building

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

Edit this page on GitHub · Read it as Markdown

    Type to search. Arrow keys move, Enter opens.