reminisce

Agent memory on TypeDB: an Elixir library with an MCP face.

Status: 0.5.0. Its releases are on Hex.
While it is 0.x, a minor version may change the public API;
docs/CHANGELOG.md lists every such change. The design is docs/spec.md, and its §9 is the
readiness test this release passes in CI.

What it does

• Remembers what an agent decides to keep, with time (valid, occurred, due,
  recorded), provenance (basis, confidence, sources, derivations), scope (a
  subject with a consent scope) and status. One memory can have several aspects
  at once: episodic and semantic, say.
• Recalls deterministically. It ranks words after a light English and
  Russian analyser, using integer scores, and breaks ties by key. The same store
  and query give the same order whatever the insertion order or the clock. It
  considers every memory of the owner the audience may see, and each answer
  says how many it scanned. Recall has no side effects.
• Explains a memory (why/4): its sources, derivation ancestors to a chosen
  depth, what it superseded and what supersedes it, every contradiction it takes
  part in, its status history, and whether a withdrawal is complete. A
  derivation cycle ends the walk instead of hanging.
• Retires, supersedes and withdraws. It never deletes a memory.
  • forget/4 takes a memory out of recall and keeps its words: it changes
    the agent's attention, not a person's rights.
  • withdraw/4 erases a subject's words from the database: each memory's
    content and facets, the reason of any contradiction it takes part in, the
    facets of associations it is a member of, and its source links (a source
    nobody else cites goes too). The redacted entity stays, with its key, owner
    and times. A memory that supersedes one about a subject, or is derived from
    one, inherits that subject, so withdrawal reaches it. What it does not
    erase is listed under Erasure: what it does not reach.
  • purge/3 also removes the subject entity, its links and its withdrawal
    records; why then answers withdrawal: :purged. It needs
    confirm: true.
• Scopes every call to an owner. Every function that names a memory by key
  takes the owner too, and keys are per owner: two owners may use the same key,
  and another owner's key answers exactly as an unknown one does, to
  remember as to why.
• Refuses secrets at the door. A built-in guard covers the shapes of
  gitleaks' default rule families and runs before any write and before the
  host's policy. It scans every string as it will be stored (a facet as
  name=value), owners included. Its patterns are linear, and every text field
  has a size cap (Reminisce.Limits) checked before anything is scanned.
• Reads as of a past moment (as_of/4, or recall(..., as_of: t)).
• Decays and consolidates when the host calls it. The decay function is pure
  (decay/2). consolidate/3 makes one idempotent pass per owner and interval
  end.
• Backs up and restores logically. The backup is generated from whatever
  schema the database holds, host types included. Backing up, restoring and
  backing up again gives byte-identical files.
• Keeps intentions (from 0.5): a prospective memory with a due_at, or
  with cues (an event, a term, a source, a memory, the audience), is an
  intention. Recall answers the intentions now due beside its memories, never
  among them, each with the triggers that fired; fulfil/4 marks one done,
  and a pass archives one past its valid_to as expired. An :observed
  intention is never due unless the store allows it.
• Holds a focus across a session (from 0.5): a bounded value the caller
  passes from one recall to the next (Reminisce.Focus). Earlier queries of
  the session help rank later ones, but never above a memory the query itself
  matches, and an intention it has surfaced is not surfaced again. Nothing of
  it is stored.
• Weighs how a memory was felt (from 0.5): an affect, a valence and an
  arousal recorded about one of the owner's memories, whether the owner felt
  it or a person the memory concerns, makes that memory easier to recall and
  slower to fade, within bounds the store sets. It is never evidence of what
  is true, and a memory goes inactive when its twin with no affect would. An
  affect about a person needs a scope, is seen only by that person's
  audience, and goes with the person's other memories when they are
  withdrawn.
• Keeps a character, the persona DNA (from 0.5): versions of strands
  (values, boundaries, a voice, relationships and an origin), each resting
  on memories, that only the host writes. A keeper sets a version; a pass may
  propose a change of voice or relationship, which a keeper adopts or
  declines; an agent can be forked from another. Recall lifts a memory a
  strand rests on, a little, and never above what is true. Readings of the
  agent's own statements against its strands report drift. No text, tool
  result or memory changes it. A strand about a person needs a scope, is
  shown only to that person's audience, and goes when they withdraw.
• Speaks MCP over stdio with eight tools: memory_remember,
  memory_intend, memory_affect, memory_recall, memory_fulfil,
  memory_forget, memory_why and memory_persona, which only reads. A
  server serves exactly one owner, fixed at start, and keeps one focus per
  connection.

What it does not do

• It does not decide what is worth remembering. That is the agent's call, or
  the host's Reminisce.Policy.
• It does not call a model. Summarising, abstraction, contradiction finding
  and autobiography belong to the host. The library stores what such a pass
  produces, as basis: :generated.
• No vectors, no embeddings, no query expansion in this release. There is a
  Reminisce.Similarity port with no implementation. expand: accepts only 0.
• No scheduler. It has no cron and no job queue: the host runs
  consolidate/3.
• It does not hold working memory or transcripts. Store what the agent
  decided to keep, not the log.
• It does not judge whether a source is true.
• The secret guard finds shapes, not intent. A secret in a shape it does not
  know gets through. Your policy is the second line.
• It cannot tell whether unscoped text is about a person. Keeping personal
  data out of unscoped memories is the host's job.
• It does not detect special categories such as health, beliefs or
  sexuality, and adds no protection for them. A host that stores them names that
  in consent.
• Withdrawal does not reach everything. Keys stay, and so do memories not
  linked to the subject, sources other memories still cite, backups, copies in
  the host, and the bytes on disk until TypeDB compacts them. The list is under
  Erasure: what it does not reach.
• It isolates owners, not tenants. Every call that names a memory is
  scoped to its owner, and keys are per owner, but all owners share one
  database and its credentials. Anyone who can query the database reads every
  owner's memories, and backup/2 copies them all. Subjects are not per owner:
  two owners that use the same subject reference name the same subject, and
  withdraw/4 and purge/3 reach both owners' memories of it. Tenants that
  must be kept apart each need a database of their own (one Reminisce.Store
  each).
• Recall has no index. Every recall reads every active memory of the owner
  the audience may see: about 2 s and 37–55 MiB at 10,000 memories, and
  27–30 s and 358 MiB at 100,000, on the machine named there
  (measured). It suits owners with thousands of
  memories, not hundreds of thousands.
• It is not legal advice. Withdrawal removes the words, and the subject
  reference is meant to be a pseudonym whose mapping the host deletes. Whether
  that meets a given law's erasure duty is for you and your counsel.

Requirements

Elixir 1.19 or newer on Erlang/OTP 28 or newer, and TypeDB 3.12 or newer.
CI runs Elixir 1.19 on OTP 28 and 1.20 on OTP 29. On OTP 27 the VM's own
terminal reader can take the MCP server's first input before the server reads
it, and Elixir 1.18 cannot compile the library on OTP 28.

Every query passes its values through TypeQL's given stage, and nothing is
built by string concatenation from caller input. It runs on the
typedb driver over HTTP, using Finch.

Install

Add it to the deps in your mix.exs:

{:reminisce, "~> 0.5"}

Or, from its git repository at a release tag:

{:reminisce, git: "https://github.com/NoeticEcho/reminisce-elixir.git", tag: "v0.5.0"}

Then run mix deps.get. The library needs a TypeDB server to talk to;
scripts/typedb-server start runs one on this machine for development and
tests.

Quick start

test/readme_test.exs runs this block as it stands.

{:ok, _} =
  TypeDB.start_link(
    name: :memory_db,
    url: "http://localhost:8000",
    username: "admin",
    password: pw
  )

store = Reminisce.Store.new(:memory_db, "memory")
:ok = Reminisce.setup(store)

owner = {"agent", "alice"}

{:ok, m} =
  Reminisce.remember(store, owner, %{
    content: "The north gate opens at dawn.",
    aspects: [:episodic],
    basis: :observed,
    sources: ["doc:gates"],
    facets: [{"place", "north gate"}]
  })

{:ok, %{memories: [^m | _], scanned: 1}} =
  Reminisce.recall(store, owner, "when does the gate open")

{:ok, %{memory: ^m, sources: ["doc:gates"]}} = Reminisce.why(store, owner, m.key, depth: 5)

{:ok, _} = Reminisce.forget(store, owner, m.key, reason: "the gate was rebuilt")
{:ok, %{memories: []}} = Reminisce.recall(store, owner, "when does the gate open")

The URL above is a server on the same machine. A TypeDB server anywhere else
should be reached at an https:// address: the driver signs in with the
password and then sends a token with every request, and over plain http://
both cross the network as they are.

An https:// server's certificate is checked against the operating system's
trust store. For a server whose certificate a private authority signed, the
MCP server (below) reads that authority's PEM file from TYPEDB_CACERTFILE;
the library takes it as Finch's transport_opts in TypeDB.start_link/1's
:http option.

Every function returns {:ok, _} or {:error, reason} (setup/1 returns
:ok), and none raises for a domain refusal. Error reasons name rules and
fields, and keys only of memories that exist; never a memory's words, and never
a caller's input echoed back (an unknown key is plain :not_found). A store the library could not reach is an error,
never an empty answer.

The API

remember/3 attributes

Intentions and the focus

An intention is due at a recall when it is active, inside its valid_from to
valid_to, visible to the audience, not held by the focus given, of a basis
the store's intentions: [due_bases: …] allows (default [:told, :inferred, :generated]: an :observed one is found by its words but never due), and one
of its triggers fires: its due_at has come, an event in :events matches,
or the focus the recall answers holds its term, its source or its memory (the
focus holds the session's query terms, the memories recalled and the sources
they cite). due answers at most due_k, earliest due_at first and those
with none after, each as %{memory:, because:}. This block runs as it stands
too:

{:ok, _} =
  TypeDB.start_link(
    name: :plans_db,
    url: "http://localhost:8000",
    username: "admin",
    password: pw
  )

store = Reminisce.Store.new(:plans_db, "memory")
:ok = Reminisce.setup(store)
owner = {"agent", "alice"}

{:ok, plan} =
  Reminisce.remember(store, owner, %{
    content: "Check the rota before the review.",
    aspects: [:prospective],
    basis: :told,
    cues: [{:event, "rota_review"}]
  })

{:ok, %{due: [%{memory: %{key: key}, because: ["event:rota_review"]}], focus: focus}} =
  Reminisce.recall(store, owner, nil, events: ["rota_review"])

^key = plan.key

{:ok, %{due: []}} = Reminisce.recall(store, owner, nil, events: ["rota_review"], focus: focus)
{:ok, _} = Reminisce.fulfil(store, owner, plan.key, reason: "checked")

A recall with :focus is one turn of a session, and answers the next focus.
The focus holds at most size cues (default 32): the query's terms, the
memories recalled and their sources, each fading by turn. A focus term scores
half of what the same term scores in a query, a memory's whole focus part is
capped at half the smallest weight of the query's terms, and so a memory the
query matches always ranks above one only the focus brings in. A focus given
for another owner or audience is dropped, and the answer says
focus_reset: true. parts gives, for each memory, what the query and the
focus added. docs/spec.md §A.2 and §A.5 are the rules in full.

Affects

An affect records how one of the owner's memories, its object, was felt:
a valence from −1,000 (unpleasant) to 1,000 (pleasant) and an arousal
from 0 (calm) to 1,000 (intense), integers, with a basis, :told (the one
who felt it said so) or :generated (a model's reading), and a holder, the
owner or {:subject, ref}. It is a memory itself, with the aspect
:affective, whose grounds are its derived_from and sources. This block
runs as it stands too:

{:ok, _} =
  TypeDB.start_link(
    name: :felt_db,
    url: "http://localhost:8000",
    username: "admin",
    password: pw
  )

store = Reminisce.Store.new(:felt_db, "memory")
:ok = Reminisce.setup(store)
owner = {"agent", "alice"}

{:ok, outage} =
  Reminisce.remember(store, owner, %{
    content: "The release broke the login page for an hour.",
    aspects: [:episodic],
    basis: :told
  })

{:ok, felt} =
  Reminisce.affect(store, owner, outage.key, %{valence: -600, arousal: 800, basis: :generated})

{:ok, %{memories: [found], scores: [score], parts: [%{affect: lift}]}} =
  Reminisce.recall(store, owner, "login page")

[%{key: key, weight: 800}] = found.affects
^key = felt.key
^lift = div(score - lift, 5)

{:ok, %{affects: [%{key: ^key}]}} = Reminisce.why(store, owner, outage.key)

{:ok, _} = Reminisce.forget(store, owner, felt.key, reason: "read again, it was milder")
{:ok, %{memories: [%{affects: []}], parts: [%{affect: 0}]}} =
  Reminisce.recall(store, owner, "login page")

An affect weighs how readily its object is recalled, never whether it is
true. Its weight is its arousal times its own salience, which starts at 1
and fades as any memory's does (here 800 × 1), at most the store's
observed_cap (250 by default) when it rests on outside text: an
:observed object or ground, or sources. Recall multiplies the
score of a memory the query or the focus matches by (1,000,000 + recall_weight × weight) / 1,000,000, rounded down: at most (1000 + w) / 1000, with w 250 by default and 500 at most. Two affects on one memory
lift it no more than the stronger, valence weighs nothing, and a claim of a
contradiction that stands is never lifted. parts.affect is what the
affects added. An affective memory takes no part in a relation, grounds
only another affect, and is returned by recall only when aspects: names
:affective. A pass slows the decay of a memory by the affects the owner
holds that concern no subject, and tests inactive_below against its
salience with no affect, unslowed_salience, so an affect never keeps a
memory active.

One object, holder and basis has one active affect. A second is
{:error, {:exists, key}}; supersede/4 of the first revises it, and
forget/4 clears it, as above. remember/3 and supersede/4 take
affects: to write a memory and its affects in one transaction.

An affect about a person is about a person. An affect concerns the
subjects of its object and of its grounds, and its holder, and needs an
affect_scope on each of them, the reason it is kept. It weighs and
appears in recall and why/4 only for its own audience (subject:), never
for another or for none, and changes no stored number of its object. A
model's reading of a person, a :generated affect a subject holds, is
refused unless the store has affect: [appraise_subjects: true], which
needs a subject_retention_days, and is never written with words.
withdraw/4 deletes an affect's numbers and holder with its words, and
only: :affect withdraws a subject's affects alone; after that, a new
affect concerning the subject needs reviewed_by. With
subject_retention_days: n, a pass erases, as a withdrawal would, the
affects concerning a subject recorded more than n days before its
interval end. docs/spec.md Appendix B is the design in full.

The persona DNA

The DNA is the agent's character as its keeper set it: numbered versions,
each holding 1 to 128 strands. A strand has a kind (:value,
:boundary, :voice, :relationship or :origin, one at most), a name
and words, and rests on memories of the agent's, its derived_from. It is
a memory itself, with the aspect :persona. All five writers are the
host's, in Elixir; no tool calls one. This block runs as it stands too:

{:ok, _} =
  TypeDB.start_link(
    name: :dna_db,
    url: "http://localhost:8000",
    username: "admin",
    password: pw
  )

store = Reminisce.Store.new(:dna_db, "memory")
:ok = Reminisce.setup(store)
agent = {"agent", "desk"}

{:ok, asked} =
  Reminisce.remember(store, agent, %{
    content: "The night shift asked for short answers.",
    aspects: [:semantic],
    basis: :told
  })

{:ok, v1} =
  Reminisce.persona_set(store, agent, %{
    reason: "the first version",
    persona_set_by: "keeper-1",
    strands: [
      %{name: "plain", kind: :voice, content: "Plain words.", derived_from: [asked.key]},
      %{name: "no_secrets", kind: :boundary, content: "Never shares a secret it was told."},
      %{name: "made", kind: :origin, content: "Made by the keepers."}
    ]
  })

{1, :adopted} = {v1.number, v1.status}
keep = fn version, names -> for s <- version.strands, s.name in names, do: %{keep: s.key} end

# A pass may propose a change of voice or relationship, never of a boundary.
{:error, {:invalid, :strand_kind}} =
  Reminisce.persona_propose(store, agent, %{
    reason: "fewer rules",
    persona_proposed_by: "pass-1",
    basis: :generated,
    strands: keep.(v1, ~w(plain made))
  })

{:ok, %{number: 2, status: :proposed}} =
  Reminisce.persona_propose(store, agent, %{
    reason: "brisk at peak",
    persona_proposed_by: "pass-1",
    basis: :generated,
    strands:
      keep.(v1, ~w(plain no_secrets made)) ++
        [%{name: "brisk", kind: :voice, content: "Brisk when the queue is long."}]
  })

{:ok, v2} = Reminisce.persona_adopt(store, agent, 2, %{persona_set_by: "keeper-1"})
{:ok, %{added: %{voice: ["brisk"]}}} = Reminisce.persona_change(store, agent, 1, 2)

# Recall lifts the memory a strand rests on: parts.persona is what it added.
{:ok, %{memories: [found], parts: [%{persona: lift}]}} =
  Reminisce.recall(store, agent, "night shift")

true = found.key == asked.key and lift > 0
{:ok, %{defines: [_]}} = Reminisce.why(store, agent, asked.key)

# The host reads the agent's statements against the strands.
{:ok, said} =
  Reminisce.remember(store, agent, %{
    content: "I kept it short tonight.",
    aspects: [:autobiographical],
    basis: :generated
  })

[plain] = for s <- v2.strands, s.name == "plain", do: s.key

{:ok, 1} =
  Reminisce.persona_read(store, agent, [
    %{statement: said.key, strand: plain, stance: :holds, basis: :generated}
  ])

{:ok, %{alerts: []}} = Reminisce.persona_drift(store, agent)

The keeper sets, a pass proposes. persona_set/3 writes a whole
version, with the basis :told, and adopts it at once. Without a
reviewed_by it is held, {:error, {:held, :review}}, when it adds,
changes or drops a value, a boundary or the origin (the first version
aside), or adds a strand about a subject whose strands were withdrawn on
their own. persona_propose/3 changes only voice and relationship strands
that concern no one, at most max_changed of them (2 by default), with the
basis :generated or :told; persona_adopt/4 adopts it while no version
has been adopted since (else {:error, {:stale, current}}), and holds a
proposal whose new strands rest on outside text, sources or an :observed
memory among their grounds, without a reviewed_by. persona_decline/4
declines it. Every version stays in the store, and persona/3 answers any
of them, with as_of: the one current at a time.
c:Reminisce.Policy.check_persona/3 sees each set, adoption and fork last.

It weighs recall, never truth. Recall multiplies the score of a memory
a strand of the current version rests on, when a term of the query scores
it (the focus alone never does), by (1000 + recall_weight) / 1000,
rounded down, after an affect's multiplier: recall_weight is 100 by
default, 250 at most, and 0 turns the lift off. A claim of a contradiction
that stands is never lifted. why/4 answers the strands a memory defines
and the readings of it. A strand is never a candidate of recall nor a cue
of the focus: persona/3 answers it, and as_of/4 among the memories. A
pass never decays it; forget/4, supersede/4, relate/5,
mark_recalled/3 and affect/4 refuse it, and no memory rests on one.

Drift is read, not guessed. persona_read/3 records that a statement
of the agent's holds to or departs from a strand. persona_drift/2 counts
them over windows (6 of 30 days by default), by the strand's name, a memory
once by its latest reading; it names in alerts a strand whose latest
window has at least drift_min readings (5) with at least drift_alert
(300) thousandths departing, and lists the autobiographical memories no
reading covers. It names memories about people: it is the host's, and no
tool answers it.

A fork carries no one unnamed. persona_fork/4 gives another agent a
version 1 with a copy of each of the parent's strands that concerns no one,
the origin aside: the child names its own. A strand about a person goes
only by name in carry:, with the child's own consent and scope. The
child's answers name no other owner.

A strand about a person is about a person. A strand that concerns a
subject, given or through its grounds, needs a persona_scope on each
link, from every writer. It is shown, by persona/3, recall, why/4 and
memory_persona, only to that subject's audience, and counted in a change
only for it. withdraw/4 strikes it with the subject's other memories, and
only: :persona strikes the subject's strands alone, with their scopes and
readings. docs/spec.md Appendix C is the design in full.

Upgrading from 0.2, 0.3 or 0.4

0.3.0 and 0.4.0 were never released: a store of theirs comes from a
development build, and a store of 0.2.0 or 0.2.1 is a 0.2 store. 0.5's
setup/1, and the MCP server at boot, refuse a store whose library
types are an earlier release's with {:error, {:upgrade_needed, "0.2" | "0.3" | "0.4"}}. To upgrade, stop writes, take a backup (backup/2), and call
upgrade/1, or run mix reminisce.mcp --upgrade --database …
(bin/reminisce-mcp --upgrade in the downloaded server), which takes the
backup itself and names its directory. It takes it before the upgrade's
checks, so when they refuse the store (a type that already has a name the
upgrade adds, or a memory with the aspect persona or affective), the
backup is there, holding the store as it was, and nothing is defined.

From 0.4 the upgrade defines the persona's ten attributes, its entity
persona_version and its four relations, writes no data and converts
nothing: a 0.4 store has no DNA, and recalls and decays as before. It
refuses, defining nothing, a store where a memory already has the aspect
persona, which 0.5 keeps for strands, with {:error, {:aspect_taken, :persona, count}}.

From 0.3 it also defines the five attributes and two relations of
affects, writes no data and converts nothing: a 0.3 memory has no affect,
and recalls and decays as before. It refuses, defining nothing, a store
where a memory already has the aspect affective, which 0.4 keeps for
affects, with {:error, {:aspect_taken, :affective, count}}: rename that
aspect first.

From 0.2 it also defines cue, intention_outcome and fulfilment, and
counts the 0.2 prospective memories with a due_at that become intentions,
how many of them due_bases keeps out of due, and how many the next pass
expires: those whose valid_to is at or before the store's clock at the
upgrade (a pass given a later now also expires any that have passed
since). Every memory recalls as it did before, and a second upgrade/1
answers {:ok, :current}.

Hooks

• Reminisce.Policy: check(owner, attrs) :: :ok | {:hold, :review} | {:refuse, atom}. It runs before every write, after the secret guard, and
  sees each new strand as the memory it is. The optional
  check_persona(owner, version, context) sees a set, an adoption or a fork
  of the DNA last, with its change and drift: a bound over time belongs
  there.
• Reminisce.Analyser: terms(text) :: [term]. The default folds English
  and Russian.
• Reminisce.Similarity: scores(owner, query, keys). It is asked about
  each page of recall's candidates, by the owner's own keys. If it fails, recall
  reports
  similarity: {:unavailable, reason} and still answers.
• Telemetry: there is one [:reminisce, op, :start | :stop | :exception]
  span per operation, and a [:reminisce, :guard, :refused] event. No event
  carries content. See Reminisce.Telemetry.

Store options include :policy, :analyser, :aspects, :review_aspects,
:page_size (default 2,000), :decay, :withdraw_batch (default 500),
:withdraw_keep (default []), :clock, and :affect, with
recall_weight (0 to 500, default 250), decay_slowing (0 to 1, default 1),
appraise_subjects (default false), observed_cap (0 to 1,000, default
250) and subject_retention_days (default nil), and :persona, with
recall_weight (0 to 250, default 100), max_changed (1 to 16, default 2),
drift_alert (0 to 1,000, default 300) and drift_min (default 5). See
Reminisce.Store.

Extending the schema

A host may define its own attributes, its own subtypes of memory and its own
relations, in its own define, after setup/1. setup/1 checks only the
library's types. backup/2 exports every type in the database.

A withdrawal deletes every attribute a host defined on memory unless the
store's :withdraw_keep names it. Name identifiers there, such as a tenant id,
never words. An attribute the host makes required (@card(1..1)) must be
named, because it cannot be deleted: without it in the list, a withdrawal of a
memory that has it fails and leaves the words in place.

The library's types have plain names, with no prefix: memory, content,
status, subject and so on (Reminisce.Schema lists them). In a database
where a host type already has one of those names, setup/1 defines nothing.
It answers {:error, {:schema_differs, facts}}, even when the definitions
agree. A host in that position gives the library a database of its own. The
design (docs/spec.md §5.6) says why there is no prefix, and what a rename
would cost a host that has data.

The MCP server

mix compile   # first: Mix's own compile output would go to stdout
TYPEDB_PASSWORD=… mix reminisce.mcp --owner agent:alice --database memory

Logs go to stderr; stdout carries JSON-RPC and nothing else (a test starts
the task as an OS process and parses every stdout line).

The server also comes without Elixir: from 0.5.0, each GitHub release
carries it as reminisce-mcp-VERSION-OS-ARCH.tar.gz, for macOS 13 or newer
and for Linux with glibc 2.28 or newer, on arm64 and x86_64, each with its
SHA-256 beside it. Check the file against its checksum, unpack it, and run
bin/reminisce-mcp with the options and environment above
(what it is, and why).

Before it serves, the server checks its TypeDB, and stops with a sentence that
says what to do when the URL does not answer, answers as something other than
TypeDB 3's HTTP API, is a TypeDB older than 3.12 (or not 3.x), refuses the
password, or lacks the database. It creates a database that does not exist,
with its schema; --no-create makes an absent database an error instead.
--init sets the database up and exits without serving (no --owner
needed). The password is read from TYPEDB_PASSWORD only, and a URL with a
user name or password in it is refused.

TypeDB in one command, with Docker:

TYPEDB_PASSWORD=… plugin/typedb/first-run

It starts TypeDB 3.12.1 (plugin/typedb/compose.yaml: the image by digest,
listening on 127.0.0.1:8000 only, its data in a named volume, its usage and
error reports off), waits until it serves, replaces the admin user's default
password with TYPEDB_PASSWORD, and creates the database reminisce and its
schema. A second run changes nothing. It writes no file, puts the password on
no command line, and refuses TypeDB's default password. The server it sets the
database up with is REMINISCE_MCP_SERVER (plugin/server/bin/reminisce-mcp
when unset); REMINISCE_DATABASE and REMINISCE_TYPEDB_PORT change the
database and the port. docker compose -p reminisce-typedb down --volumes
removes it with its data.

The server speaks JSON-RPC 2.0 over stdio, one message per line, and uses no MCP
library. It reads standard input as bytes, from file descriptor 0 itself, and
writes bytes, whatever the locale: a line must be UTF-8, and one that is not
is answered as a parse error. \r\n ends a line as \n does, an empty line is
skipped, and a last line with no newline is still read.

It never holds more than 1 MiB of one line. A longer line is answered as
Request too large while it is read, and skipped.

The reader counts the lines it has handed to the server and not yet seen
answered, and the bytes of those lines:

• It stops reading once more than 4 MiB, or more than 4,096 lines, are
  waiting.
• It starts again once no more than 1 MiB and 1,024 lines are waiting.
• One read takes at most 64 KiB, and one read can pass either bound before
  the reader stops. So at most a further 64 KiB, or 65,536 empty lines, can
  be waiting.

A client that writes faster than the server answers therefore leaves its
backlog in the pipe. Two tests in test/mcp/stdio_test.exs measure this
against the real OS process:

• 96 lines of about 1 MiB sent to a server that is stalled writing: the
  server read 4 to 5 MiB of the 96 from the pipe in the runs measured for
  this release (its rchar in /proc/<pid>/io), and the writer stays
  blocked. The test fails at 16 MiB read, and fails if the writer finishes.
• 20,000 pings and 8 MiB of empty lines sent to a server that is stalled
  writing: the server grew by 0 to 1 MiB, and the writer stays blocked. The
  test fails at 16 MiB.

Input that cannot be read is answered with one error (-32000, Input read failed), and the task exits with status 1. The end of input exits 0. A
message whose handling crashes is answered as an internal error that names
nothing from it, and the server goes on. A host that calls
Reminisce.MCP.Server.run/4 from its own code gets its devices' encoding and
its logger filters back when the call returns.

Every argument is checked against its declared maxLength and maxItems
before a tool runs. The caps are those of Reminisce.Limits, in bytes of
UTF-8: text outside ASCII fits fewer characters than maxLength says.

One server is one owner. No tool takes an owner, and a call that names one
is refused with owner_is_fixed. Keys are per owner in the library itself
(Reminisce.Keys), so the server's owner never meets another owner's key: a
key another owner holds answers exactly as one nobody holds, to every tool. A
message without an id is a notification and never runs a tool. withdraw is
not a tool: withdrawal is a person's right, exercised through the
host. No tool writes the persona DNA or its readings: those are the keeper's,
through the host. A tool's structuredContent is exactly Reminisce.Output applied to the
direct Elixir call's answer.

One connection is one session. The server keeps a focus for each
connection, as process state: never stored, never logged, bounded as
Reminisce.Focus is. Each memory_recall passes it and keeps the one
answered, and the connection's first recall that succeeds is told of the
event session_start.

Erasure: what it does not reach

withdraw/4 and purge/3 remove a subject's words from the memories linked to
that subject: every attribute a withdrawn memory owns except the library's
bookkeeping (key, owner, aspects, basis, confidence, salience, recall counts,
times, status and reviewer) is deleted, including attributes a host defined on
memory, except those the host names in :withdraw_keep. An affective
memory concerning the subject loses its valence, arousal and felt_by
with its words, and each of its links its affect_scope; only: :affect
does that to the subject's affective memories alone, and keeps the words of
the rest. They do not reach:

• Keys. A memory's key stays after a withdrawal and after a purge. Choose
  keys that carry no words: the library's own (m_…) or opaque ids, never
  "ola-fears-the-river".
• Memories not linked to the subject. An unscoped memory that mentions the
  person by name is not reached. Superseding and derived memories are linked
  automatically; anything else must carry the subject when it is written.
• Sources cited elsewhere. A withdrawn memory's source links go, and so
  does a source no other memory cites. A reference that another memory still
  cites stays, because that memory still cites it.
• The withdrawal's own record. Its reason is the host's text and stays
  until a purge, so it must not quote the person.
• Backups. A backup taken before the withdrawal still holds the words.
  Expire old backups, or withdraw again after restoring one.
• Copies outside the store. Logs, job arguments and caches in the host
  (see the next section).
• Disk. The words are gone from every answer the database gives. When the
  storage engine reclaims the bytes on disk is TypeDB's (RocksDB compaction),
  not the library's.
• A memory written while a withdrawal finishes. TypeDB lets the
  withdrawal's last transaction and a concurrent write about the same subject
  both commit. Such a memory stays visible: why/4 answers withdrawal: :missed when it was recorded before the withdrawal's record, and the next
  withdraw/4 redacts it in any case. Stop writing about a subject before
  withdrawing it. A purge has no such window: a concurrent write makes it fail
  with {:error, :conflict} and delete nothing.

Rules for hosts

• Text lives only in the store. If you schedule the library's work, put keys
  in job arguments, never words. Otherwise a withdrawal cannot reach your job
  table.
• subject must be a pseudonym. Keep the mapping from pseudonym to person in
  your system. To honour an erasure request, call withdraw/4 first, then
  delete your mapping.

Measured on this release

• Withdrawal size. Measured by bench/withdraw.exs (one owner's
  memories, all about one subject; the machine is below):

  • 10,000 memories in batches of 500 (the default): 10 s;
  • 10,000 memories in batches of 4,000: 25 s;
  • 50,000 memories in batches of 500: 425 s, about 7 minutes;
  • 50,000 memories in batches of 4,000: 991 s, about 16.5 minutes.

  The time grows faster than the number of memories, and larger batches make
  it longer, not shorter.

  A batch's update must fit one request (under 2 MiB on TypeDB 3.12), so no
  batch exceeds 4,000 memories, whatever the length of their keys. The default
  batch is 500. A withdrawal that fails part way reports
  {:withdrawal_incomplete, %{redacted: n}} and writes no withdrawal record,
  so why/4 says :incomplete until a rerun finishes.

• Recall considers every active memory of the owner the audience may see,
  in one read transaction: it reads the owner's keys in one sorted answer, then
  fetches the memories by key, page_size (default 2,000) at a time. Nothing
  is left out and nothing is indexed, so every recall pays for every memory the
  owner holds, in time and in memory. One recall, measured by
  bench/recall.exs (the machine is below; memories of about 70 bytes of
  content; for each query, the median of three runs after a warm-up, and the
  peak growth of the BEAM's memory during the call). Each recall returns at
  most k = 8 memories, the default. Of the three queries, "w17 w42" and
  "w1999" match more memories as the store grows (the columns give how
  many), and "nothing-matches-this" matches none:

  the owner's memories	matching "w17 w42"	matching "w1999"	time	memory
  2,000	17	9	0.41–0.49 s	23–27 MiB
  10,000	109	59	2.1–2.2 s	37–55 MiB
  50,000	587	285	12.8–13.0 s	174 MiB
  100,000	1,185	555	27–30 s	357–358 MiB

  The cost is about the same whether a query matches a thousand memories or
  none: every memory is read either way. A recall with no query, as_of/4
  and consolidate/3 walk the same way.

• The machine. Every figure above was measured on one virtual machine:
  an Intel Xeon at 2.10 GHz with 4 schedulers online and 15.7 GiB of memory,
  Linux 6.18, Elixir 1.20.4 on Erlang/OTP 29, and TypeDB CE 3.12.1 on one
  node on the same machine. The raw outputs, each headed with the machine it
  ran on, are in bench/results/.

The readiness tests

test/criteria/ has one file per criterion in docs/spec.md §9, §A.9,
§B.10 and §C.12:

1. Round trip: every type, the DNA's among them, a withdrawn memory, a
   contradiction whose claim is a derivation, and a host-defined attribute.
2. Nothing deleted: 1,000 random operations.
3. Withdrawal: the words are absent from backups, content and every public
   output, including withdrawals that are batched and interrupted.
4. Secrets: 48 shapes (two in each of 24 rule families) refused through
   remember and memory_remember. No trace in logs, telemetry, errors or MCP
   responses, checked also on paths that reach the database with a secret in
   hand, with canaries proving each capture works. Near-misses refused: 0 of
5. Deterministic recall: 20 queries over 50 shuffled insertion orders, read
   in one page and in pages a third of the fixture.
6. why: a 4-deep chain, a supersession, a contradiction, two sources, and an
   injected cycle, within 5 s.
7. Import: directories of invented JSONL records, each with 20 held-out
   query and record pairs. The first set's pairs were committed before the
   importer; the second set's (test/fixtures/import_b) before any of its
   records was written. The same hand wrote queries and records in both,
   so this measures recall on realistic paraphrase, not on strangers' words.
   Currently 20 of 20 in the top 8 for each set.
8. MCP: each tool equals the direct call, and the owner cannot be
   overridden.
9. Publishable: LICENSE and NOTICE are present and the tree is clean of
   foreign ids. CI's gitleaks job checks the full history.
10. Intentions: a session of 30 intentions and 20 recalls whose due lists
    were written down by hand before the code, under the default due_bases
    and with :observed allowed; expiry by pass; the bound of 64 surfaced
    keys. Each guard (surfaced, not_before, expiry, audience, due_bases,
    active) is taken out in turn, and the lists change.
11. The persona is immune to data: 40 or more texts, in English and in
    Russian, that ask for the persona to change or claim to be the keeper or
    the persona, through every public function and MCP tool that takes text
    but the seven that write the DNA by design: the DNA after them is
    unchanged.
12. Focus: the same answers for 50 insertion orders; the bound held over
    random sessions; a focus term never outscoring the query's; §A.5's case
    built to break the cap, which breaks when the cap is taken out; the reset
    for another audience; no query word in telemetry or logs.
13. Still nothing deleted: criterion 2's 1,000 random operations, with
    intentions written, surfaced, fulfilled and expired, affects written and
    erased, and the DNA set, proposed, adopted, declined, forked, read and
    withdrawn: no memory and no version is lost.
14. An upgraded store answers as it did: stores made by 0.2.1, 0.3.0 and
    0.4.0 from invented records, kept as backups, recall in their release's
    order after upgrade/1, and their round trips are byte-identical.
15. An affect weighs salience, within its bound, and never truth.
16. An affect decays and is consolidated as written.
17. A text cannot make an affect.
18. An affect about a person is about a person.
19. Only the keeper's act changes the DNA, and every version says whose:
    a scripted history against tables worked out by hand.
20. The DNA weighs order, within its bound, and never truth: the lift's
    arithmetic, a case built to fail with the focus rule taken out, and a
    twin with no DNA.
21. Drift is read as written, and the agent cannot hide it: six windows
    against a hand table, and an attack over MCP. The gaps §C.5 states are
    printed as such, not passed.
22. A fork carries what it says, and no one.
23. A persona that names a person is that person's: every writer needs a
    scope, other audiences see a twin's answers, and both withdrawals, 0.4's
    and 0.5's, strike the person's strands.

Criterion 11 (appraisal) is replaced by 16 to 19 for 0.4 (docs/spec.md
§B.10).

Tests tagged :typedb need a server (scripts/typedb-server start). Without
one they are excluded, and the run says so.

Licence

Apache-2.0. See LICENSE and NOTICE. TypeDB™ and
TypeQL™ are trademarks of TypeDB Ltd. This project is not affiliated with it.