Obsidian + agent memory

Two memory layers that work together

Structured session memory lives in .agent_notes.json (keys like fact:api-limit, reflection:turn-42, user:name). The Obsidian vault is long-form, link-rich knowledge in markdown files under typed folders. recall_relevant searches both when scope=both (default): notes for quick facts, vault for briefs and linked research.

The harness protocol tells the model: memory_query / recall_relevant first, then vault_search / vault_read, then web only if local knowledge is insufficient. That ordering keeps coding sessions grounded in what you already wrote down.

How the vault path is resolved

Precedence is explicit: AGENT_VAULT_PATH wins when set to an absolute folder. Otherwise, if AGENT_OBSIDIAN_DISCOVER is on (default), core reads Obsidian’s global obsidian.json (Windows: %APPDATA%\Obsidian, macOS: Application Support, Linux: XDG config) and picks a vault only when unambiguous — exactly one vault, exactly one with open: true, or a unique latest ts. With multiple vaults and no signal, set AGENT_VAULT_PATH or AGENT_OBSIDIAN_VAULT_NAME_SUBSTRING to disambiguate.

If discovery fails, the harness falls back to ~/.agent_vault and creates typed subfolders (Facts/, Entities/, Reflections/, Recipes/, Tasks/, Notes/, Episodes/).

# Explicit vault (recommended for CI or multiple vaults)
AGENT_VAULT_PATH=C:/Users/you/Documents/MyVault

# Auto-pick from Obsidian app (single-vault setups)
AGENT_OBSIDIAN_DISCOVER=1
AGENT_OBSIDIAN_VAULT_NAME_SUBSTRING=work

# Hybrid semantic + keyword recall
AGENT_EMBED_MODEL=qwen/qwen3-embedding-8b
AGENT_MEMORY_GRAPH=1

Vault tools (what the agent can do)

• vault_write — create/update markdown with YAML frontmatter (title, type, tags, timestamps) and [[wikilinks]] in the body.
• vault_read — load a note by title slug.
• vault_search — BM25 over vault bodies (literal/keyword oriented).
• vault_links / vault_graph — backlinks and graph traversal inside the vault.
• vault_delete — remove a note when curation allows (often after archive).
• remember / forget — atomic key-value notes in .agent_notes.json; forget archives to notes.archive.json when AGENT_MEMORY_ARCHIVE is on.
• recall_relevant — hybrid ranked retrieval across notes + vault (see below).
• memory_graph — BFS over links[] edges in structured notes after a seed key.
• memory_query — exact, type, or graph modes when you need structured joins.
• curate_memory — LLM-proposed prune/merge with deterministic safety rails (dry-run by default).
• consolidate_chat — on-demand auto-dream pass over a session JSONL.

Inside recall_relevant (accurate behavior)

recall_relevant requires query= or queries= — never scope alone. It can run multiple sub-queries and fuse rankings with reciprocal rank fusion (RRF). For notes it combines BM25, recency, note type, confidence, and access counts into tier weights (hot / warm / cold). When AGENT_EMBED_MODEL is set, embeddings are stored in ~/.liminal/memory.index.json for notes and ~/.liminal/vault.index.json for vault paragraphs; scores blend semantic, RRF, and BM25 via AGENT_RECALL_WEIGHTS (default sem:rrf:bm ≈ 0.45:0.35:0.20).

Workspace federation: notes carry scope chat (this chat only), workspace (sibling chats in the same workspace fingerprint), or global (identity-style keys). recall_relevant exposes workspace_scope: current | all | global_only and applies AGENT_RECALL_SIBLING_DISCOUNT (default 0.85) so sibling-chat notes surface but lose ties to the current chat’s own writes. Provenance lines mark (own chat), (sibling chat <id>), or (global).

Optional HyDE passes hypothetical answer text for embedding only. expand_vault_neighbors pulls linked notes from top vault hits. Optional reranker hooks refine the candidate list when enabled.

Memory graph and linking

With AGENT_MEMORY_GRAPH=1, memory_graph(seed, depth) walks links[], supersedes, and deltaOf edges in structured notes — useful after recall_relevant surfaces a seed. AGENT_MEMORY_AUTOLINK can suggest wikilinks after remember or vault_write. Vault bodies use standard Obsidian [[Title]] links; vault_graph mirrors backlink thinking for the agent.

What the harness writes automatically

AGENT_TRAJECTORY_WRITE logs causal summaries at turn end (zero extra LLM cost). AGENT_VAULT_AUTO_WRITE can persist distilled findings to the vault when configured and vault_write is registered. AGENT_MEMORY_AUTO_EXTRACT (off by default) runs a small completion to remember facts — most teams prefer explicit remember/vault_write calls for control.

On all-tool-failure rounds the harness writes reflection: entries. Successful multi-tool turns feed the recipe library (.agent_recipe_stats.json), not spammy recipe: notes.

Curation and auto-dream

curate_memory({ dry_run: true }) returns an LLM plan plus deterministic vetoes: never prune user:/identity:/pref: keys, high-access notes, or notes younger than AGENT_CURATOR_PROTECT_MIN_AGE_HOURS. Deletes go through soft archive when AGENT_MEMORY_ARCHIVE is on; restore_memory recovers.

AGENT_AUTO_DREAM (off by default) background-consolidates session logs into memory/vault when idle thresholds are met. consolidate_chat triggers the same pipeline on demand for one chat’s JSONL.

Setup walkthrough

• 1. Install Liminal and set AGENT_API_KEY — see get-started.
• 2. Point AGENT_VAULT_PATH at your Obsidian vault (or rely on discovery).
• 3. Enable AGENT_MEMORY_GRAPH and an embed model for paraphrase recall.
• 4. Activate memory_advanced + vault families if lazy loading hides them.
• 5. In session: ask the agent to vault_write a project brief, then recall_relevant on later turns.
• 6. Open Obsidian — files appear under typed folders; edit manually anytime.

Example env block

AGENT_VAULT_PATH=/path/to/ObsidianVault
AGENT_MEMORY_GRAPH=1
AGENT_EMBED_MODEL=qwen/qwen3-embedding-8b
AGENT_MEMORY_ARCHIVE=1
AGENT_OBSIDIAN_DISCOVER=0