Skip to main content
reliquary-tc’s memory graph is not a vendor-hosted “memory feature” — it is plain Markdown files in your vault, versioned by whatever git history your vault already has, queryable with the same tools that read any other note. This page shows the actual on-disk shape (generated from a real 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 plain add_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:
produce this note (real output, ## Superseded dates are day-granularity — the note is a human-readable projection, not a full timestamp serialization):
An observation added with no 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 &lt; 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’s enforcePathAcl) — pre-checked BEFORE the SQLite insert, so a denied materialization leaves no orphan row;
  • an audit_events row is written (recordOutcome, inside dispatch) — caller, tool name, duration, result size, status, an args hash; never the raw content.
There is no separate “memory write” code path that skips this. The CLI importer described below builds its own 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 in git status/git diff like 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_commit requires execute: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.
Either way, the provenance frontmatter above (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.” Without semantic search — plain full-text, no embeddings provider needed. Real output, search_text over the same scratch vault:
Graph recall — walk the [[link]] graph from a known entity, also no embeddings needed. Real output, query_entity_graph seeded on the entity above:
With semantic search — 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):
Memory tools (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:
Every write goes through the SAME per-vault ACL an MCP client’s calls would see — a 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:
A dry run against a 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.
This is deliberately generic — no vault-specific paths, domain names, or entity types. Fill in step 1’s “known title” / “well-known name” with whatever your own vault’s index note is actually called; everything else composes with 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

reliquary-tc memory: session one imports and writes an entity, session two starts fresh and recalls it via search, graph, and a direct read A static storyboard for now — 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.