create_entity + add_observation + link_entities run, pasted verbatim, not invented), names
the real modules every write goes through, and gives a copy-pasteable recipe for reading a small
index at session start and writing back at session close.
What an entity, an observation, and a relation are on disk
A memory entity (packages/server/src/memory/entities.ts) is one row in the
memory_entities table (SQLite, the source of truth) plus, when materialize: true (the
default), a regenerable .md projection under the vault’s memory folder — so its [[links]]
resolve in Obsidian’s own graph view. An observation is one fact, stored newline-delimited on
that row (serializeObservations/parseObservations) and rendered as one bullet. A relation
is a typed, directed edge in memory_relations, rendered as a [[wikilink]] under ## Related on
the source entity’s note. The link names the target’s note as it is filed (the entity name with
path and link characters such as / : # ^ | [ ] replaced by -), so a name holding ]] can never
close the link early, and the link still resolves to that note.
The shape below is a real note — specifically, the output of reliquary-tc memory import --from basic-memory --apply (the importer covered later on this page), which itself calls create_entity,
update_frontmatter (the imported_from/source_path/imported_at keys — the importer is what
adds those, not a bare create_entity call), and link_entities, in that order — run against a
scratch copy of
examples/scratch-vault
and then read back off disk. A note you create with create_entity/add_observation directly (an
MCP client, not the importer) looks the same MINUS the three imported_* keys — those are specific
to notes the importer touched.
reliquary_tc_id/entity_type/status are the ONLY frontmatter keys the projection owns
(packages/server/src/memory/materialize.ts’s OWNED_FM_KEYS) — every other key, including the
imported_from/source_path/imported_at provenance keys above, is preserved verbatim across
every future re-materialization (another add_observation, another link_entities). That is how
reliquary-tc memory import (below) can layer provenance onto a note without a special-cased write
path of its own — it merges frontmatter through the same update_frontmatter tool an MCP client
would call, and materialize.ts’s ordinary round-trip discipline keeps it.
Facts change: validity intervals
A plainadd_observation call still just appends — nothing below changes that. Pass an explicit
key (a short slug, ^[a-z0-9][a-z0-9_.-]*$) when you want the NEW fact to replace a specific
OLDER one instead of sitting alongside it: the prior observation with that same key is closed (not
deleted — its text stays on the note, under a new ## Superseded section) and the new text opens.
Two calls against a fresh Priya entity, one key: "team" observation superseding another:
## Superseded dates are day-granularity — the note is a
human-readable projection, not a full timestamp serialization):
key never supersedes anything and is never superseded
automatically — matching is always by this explicit key, never inferred from text similarity. To
retire a keyed fact with nothing replacing it, call add_observation with key + valid_to and
no observation at all.
To correct or remove a fact that has no key (every observation create_entity makes), call
update_observation with its observation_id — create_entity, add_observation and get_entity
all return one per observation, stable across reads. Pass observation to replace the text, or
retire: true to remove it. Nothing is deleted: the old text is closed (hidden from default reads,
visible with an earlier as_of, listed under Superseded), and a correction keeps the old
observation’s key. It needs write access to the entity’s note path, like every memory write.
The note’s ## Superseded section is on by default. Set memory.supersededInNote: false for the
vault to leave it out: the note then lists current facts only, search stops returning the old text,
and get_entity with an earlier as_of still returns it. Existing notes pick this up on their next
write.
get_entity and query_entity_graph both take an as_of (epoch ms; default now) and return only
the observations valid at that instant — valid_from <= as_of and (valid_to unset or as_of < valid_to). An as_of in the PAST excludes any observation added after that instant, even one
that is still open today. Querying the same entity above at two points in time (real output):
query_entity_graph filters every node’s observations the same way, so a graph traversal answers
“what did we believe as_of D” identically to a direct get_entity call on each node it passes
through.
The ACL/audit pipeline these writes go through
Every one of those writes —create_entity, add_observation, link_entities, and
update_frontmatter — is a normal MCP tool (packages/server/src/tools/m5/memory-tools.ts,
packages/server/src/tools/m1/frontmatter-tools.ts), dispatched through
ToolRegistry.dispatch (packages/server/src/mcp/registry.ts). That single call site is where:
- the caller’s scope is checked (
write:memory/write:notes) against the granted set; - the folder ACL is enforced (
packages/server/src/vault/acl-path.ts’senforcePathAcl) — pre-checked BEFORE the SQLite insert, so a denied materialization leaves no orphan row; - an
audit_eventsrow is written (recordOutcome, insidedispatch) — caller, tool name, duration, result size, status, an args hash; never the raw content.
ToolRegistry, registers the real M1 (notes/frontmatter) and M5 (memory) tools, and
calls registry.dispatch(...) for every entity/observation/relation/frontmatter write — the exact
call an MCP client makes, ACL-checked and audited the same way, with no direct file write at
all.
Read-side ACL
Reading memory follows the same folder read ACL as reading notes. Each entity has its own note at<memory folder>/<type>/<name>.md (default memory/...), and get_entity / query_entity_graph
return an entity only when read_note could read that note under your readPaths,
strictReadDefault and any rule-scopes. An entity the caller cannot read is reported exactly like
one that does not exist, is left out of by-name ambiguity and of relation lists, and is never walked
through by query_entity_graph, so the entities behind it do not appear either. Entities created
with materialize: false are gated by the path they would have. With no readPaths (the default)
nothing changes.
A relation is written into the readable entity’s note as a [[link]], so a reader of that note sees the
linked entity’s name even when the entity itself is hidden from them (its observations stay hidden).
If you set readPaths for an agent and still want it to use memory, add the memory folder to it,
for example "readPaths": ["public/**", "memory/**"]. reliquary-tc doctor --probe warns
(memory.read-acl) when your ACL hides memory entities that exist.
Git provenance
reliquary-tc does not auto-commit. Materialized memory notes are ordinary files in your vault, so “who wrote this and when” is answered the same way it is for any other note:- Plain
git log -p -- memory/note/…on the vault repo, if you keep it under git — every materialization is a normal file write (writeNoteAtomic), so it shows up ingit status/git difflike anything else you’d stage and commit yourself. - The Obsidian Git companion bridge (
git_status/git_diff/git_log/git_commit,packages/server/src/tools/m4/git-tools.ts) lets an agent drive that same repo through the ACL/ audit pipeline above —git_commitrequiresexecute:git, a hardcoded human-confirmation floor, so an agent can stage and propose a commit but never lands one without you approving it. - If your vault’s Obsidian Git plugin has its own autosave/auto-commit interval configured, that is the plugin’s own author/timestamp policy, independent of reliquary-tc.
source_path, imported_at) already answers “where
did this come from” without needing git at all — git only adds “and when did it change since.”
Recall: with and without semantic search
Without semantic search — plain full-text, no embeddings provider needed. Real output,search_text over the same scratch vault:
[[link]] graph from a known entity, also no embeddings needed. Real
output, query_entity_graph seeded on the entity above:
search_semantic embeds the query and ranks chunks by vector
similarity over the same indexed notes (including materialized memory notes, which are indexed
like any other vault content). It needs a configured embeddings provider (see
Configuration); this page does not fabricate a transcript for
a provider it did not actually call — see MCP client compatibility
for this project’s own policy on measured-only rows. The practical difference from the two recall
paths above: full-text and graph recall find what you named or linked; semantic recall also finds
what you meant — a query for “hot drink technique” would rank the coffee note above without the
word “coffee” ever appearing in it, something neither search_text nor a graph walk from an
unrelated seed can do.
Opt-in: episode_stats — memory tools in your own top activity
episode_stats (read:workspace) aggregates the experiential episode log into counts only —
never episode content — so you can see activity patterns without the fuller admin:workspace read
access work_search/work_episodes require. Real output, group_by: "tool", after a short mixed
session of create_entity/get_entity/add_observation/link_entities/query_entity_graph
calls against the same scratch vault (min_bucket: 2 — buckets smaller than that are withheld
into suppressed, a k-anonymity floor, not a redaction of these results):
create_entity, get_entity) sit at the top because this was a memory-heavy
session; run it on your own deployment after ordinary use and it reflects what YOUR agent actually
spends its calls on.
Importing memory you already have
reliquary-tc memory import brings notes from two other memory formats into this graph, through the
exact write path above — dry-run by default, --apply to write. <dir> is the source directory;
[path] (or --config <path>) is the same config-path argument every other command here takes —
a bare vault folder, a config file, or omitted to fall back to RELIQUARY_TC_CONFIG:
readOnly root
or a writePaths allowlist in the resolved config is enforced, not bypassed, for this command’s
--vault. Before touching anything, the command prints where it landed:
cacheDir that does not exist yet opens no database at all (an ephemeral
in-memory one stands in for “nothing exists yet”); against one that already exists, it opens it
read-only — a dry run never creates or writes to the cache.
Every imported note carries
imported_from/source_path/imported_at provenance frontmatter
(merged on, per the round-trip discipline above), and a re-run of --apply on the same directory
is idempotent — it is keyed on source_path, not merely on name, so an entity that already exists
with a different (or unverifiable) source_path is refused as a collision rather than silently
adopted (the same “a path that can overwrite data must be at least as strict as the path that wrote
it” discipline the vault’s own delete paths follow — collisions are reported AND make the command
exit non-zero). --resume relaxes that refusal, but ONLY for an entity with a row and zero
observations — the exact shape a run interrupted between create_entity and its follow-up
update_frontmatter leaves behind — never for one with real content already written. Two source
files whose (type, name) sanitize to the same memory-note path (an outright duplicate title, or
two different pairs that happen to collide after sanitization) are also a collision, reported at
PREVIEW time — the first file by source_path wins. Files are refused, with a reason, if they are
symlinked, dot-prefixed, or if their resolved path escapes the import directory — the same
containment guarantee (resolveVaultPathChecked, packages/server/src/vault/paths.ts) every
vault-relative path write already uses — and a missing, unreadable, or not-a-directory <dir>
fails immediately rather than reporting an empty (and misleadingly successful-looking) import.
Real dry-run output against the basic-memory fixture above (one note references a target that
does not exist in the batch, and one file has deliberately malformed frontmatter) — the banner
lines above are followed by:
--apply runs the same plan for real (mode: apply in the banner, and create becomes an actual
write — Coffee Brewing Methods relates_to Tea Brewing Methods created instead of planned).
Re-running with --apply a second time reports the same set as already present, not duplicated:
Session-bootstrap recipe
The pattern above generalizes into an ordinary session workflow: at session start, read a small index note; load only the domain block the current task needs; write back at session close. It needs no reliquary-tc feature beyond the tools already covered on this page —search_text/query_entity_graph/get_entity to read, create_entity/add_observation/
link_entities to write back. Keep the index small on purpose: it is a table of contents, not the
memory itself, so loading it never costs more than a few tool calls regardless of how large the
graph underneath grows.
vault_context (which already does an automatic, TTL-cached version
of steps 1-3 for the common case) or reflect (for a grounded synthesis instead of a raw walk) if
your deployment has them wired.
Watch it work: two sessions
docs/demo/memory-two-sessions.tape renders the animated version
(docs/public/demo/memory-two-sessions.gif) once vhs is on your PATH. Every panel above was
captured from the real commands on this page, run against a scratch copy of
examples/scratch-vault,
not invented.