obsidian-memory

name	obsidian-memory
description	Explicit-only Obsidian memory workflow. Use when the user explicitly asks to work with an Obsidian vault, LLM wiki, agent memory, RAW/source ingest, provenance, QUERY, LINT, or release safety for a markdown knowledge system. Do not auto-route ordinary coding sessions into external vault workflows.

Obsidian Memory — LLM Wiki + Agent Memory System

The agent is the operator. Obsidian is the IDE. The wiki is the codebase.

Use this skill only after an explicit user request. It touches an external vault, so treat every write as an intentional memory operation with provenance, routing, and sync consequences.

---

Architecture

Recommended vault layout:

vault/
├── wiki/                         # LLM-maintained knowledge base
│   ├── CLAUDE.md or AGENTS.md     # Vault schema and operator rules
│   ├── index.md                   # Catalog of wiki pages
│   ├── log.md                     # Operation log
│   ├── summaries/                 # One digest per source
│   ├── entities/                  # People, companies, tools, products
│   ├── concepts/                  # Methodologies, frameworks, ideas
│   ├── synthesis/                 # Cross-source answers and analysis
│   └── domains/                   # Maps of Content
├── 12-shared/                     # Shared operational memory for all agents
│   ├── memory_decisions.md        # Append-only durable decisions
│   ├── memory_routing.json        # Routing contract
│   └── scripts/                   # Optional operator tooling
├── 12-{agent}/                    # Canonical private memory per agent
│   ├── memory_active.md
│   ├── memory_corrections.md
│   ├── memory_improvements_backlog.md
│   ├── memory_heartbeat.md
│   └── memory_metrics.md
├── raw-sources/
│   ├── converted/                 # Markdown converted from raw sources; Git-tracked
│   ├── provenance/                # Source manifest and provenance docs; Git-tracked
│   ├── pdfs/                      # Local RAW cache; usually Git-ignored
│   ├── 00 RAW INBOX/              # Local intake; usually Git-ignored
│   └── quarantine/                # Conflicts/invalid sources; usually local
└── templates/

Core separation:

• wiki/ = accumulated knowledge: what the system knows and which sources support it.
• 12-shared/ = durable shared operating rules, routing, decisions, and optional scripts.
• 12-{agent}/ = private working memory for one agent only. Never mix agent-private context.
• raw-sources/converted/ + raw-sources/provenance/ = Git-safe source-derived artifacts.
• RAW binaries such as PDF/DOCX/ZIP are usually local cache, not canonical Git content.

---

Quick Reference

Operation	When	Entry point
SETUP	First time, empty vault	Create folder structure, copy assets, configure sync policy
INGEST	New source to process	RAW intake → provenance → converted markdown → wiki pages
QUERY	Need knowledge from wiki	Read index/schema → search → answer with evidence → propose synthesis if useful
LINT	Weekly or before release	Check links, frontmatter, index drift, unprocessed converted files
MEMORY	Working with agent context	Load shared + correct private memory roots in order
HOOKS	Runtime memory integration	Configure or verify SessionStart, PostToolUse, and PreCompact
BRIDGE	Checking memory-layer continuity	Run practical bridge health across RAW, wiki, graph, lessons, and drafts
TOWER	Release and closure discipline	Run release-status, branch-close, release-surface-check, decision-review, and lesson-review
QUALIFY	Testing retrieval/context ideas	Golden set -> baseline contest -> gap report -> minimal read-only trial
RUNTIME SHADOW	Evaluating optional dynamic context	Run advisory shadow/canary sessions while runtime switches remain disabled
RELEASE	Before committing/pushing	Guard RAW, verify provenance, run wiki lint, check isolation

---

Operations

SETUP — First-Time Initialization

1. Create the folder structure above.
2. Copy assets/vault-CLAUDE.md to wiki/CLAUDE.md or adapt it into AGENTS.md.
3. Copy assets/vault-index.md to wiki/index.md.
4. Copy assets/vault-log.md to wiki/log.md.
5. Copy assets/templates/ to templates/.
6. Create 12-shared/ and one private 12-{agent}/ folder per agent.
7. Add a .gitignore policy that keeps RAW binaries local while tracking wiki, converted markdown, provenance, scripts, and docs.
8. If using Git sync, configure Obsidian Git or another sync path after the RAW policy is in place.

Read references/setup.md for the detailed version.

INGEST — Adding a Source

1. Put RAW files into local intake, usually raw-sources/00 RAW INBOX/ or raw-sources/pdfs/.
2. Compute source identity before conversion: sha256, size, filename, source type, and local cache path.
3. Record or update raw-sources/provenance/raw-local-manifest.jsonl.
4. Convert source to markdown in raw-sources/converted/{slug}.md.
5. Add source frontmatter to the converted markdown.
6. Create wiki/summaries/summary-{slug}.md using the summary template.
7. Extract entities mentioned across multiple sources into wiki/entities/.
8. Extract durable ideas/frameworks into wiki/concepts/.
9. Update the relevant domain MOC in wiki/domains/.
10. Update wiki/index.md.
11. Append an INGEST entry to wiki/log.md.

Safety: never overwrite conflicting RAW files silently. If the same filename has a different hash, quarantine/report it and ask the user.

QUERY — Searching the Wiki

1. Read wiki/CLAUDE.md or AGENTS.md if not already in context.
2. Read wiki/index.md to identify domains and candidate pages.
3. Search wiki/ and, when helpful, raw-sources/converted/.
4. Read the most relevant pages.
5. Answer with an evidence section naming the pages used.
6. If the answer requires 3+ sources, is strategically recurring, or would save future work, propose a synthesis page.
7. Create wiki/synthesis/synthesis-{topic}.md only after user approval or a direct request.
8. Log meaningful QUERY operations in wiki/log.md, especially if a synthesis/runbook/index update was made.

Default QUERY behavior: answer first, propose the durable artifact second. Do not turn every useful answer into a page automatically.

LINT — Health Check

Check and report:

1. Broken wikilinks.
2. Orphan pages with no incoming links.
3. Incomplete frontmatter.
4. Stale pages.
5. Converted markdown without wiki summary.
6. Index drift.
7. Duplicate entities.
8. Provenance gaps between RAW manifest, converted markdown, and wiki summaries.

After LINT, write a LINT entry only when the operation changed files or produced a meaningful report worth preserving.

BRIDGE — Practical Bridge Health

Use practical bridges to make layer gaps visible without inventing a full ontology or mutating the vault automatically.

Recommended bridges:

1. raw -> converted
2. converted -> summary
3. summary -> domain
4. wiki -> graph
5. graph action -> review-state
6. correction -> lesson
7. lesson -> gate
8. session draft -> memory_active

Every bridge finding should include a next script-checkable step. Known backlog can remain visible without becoming a release blocker. Read references/bridge-health.md for the detailed version.

HOOKS — Runtime Memory Integration

Codex lifecycle hooks are optional but first-class runtime assets:

1. SessionStart loads bounded active/shared/correction context at startup.
2. PostToolUse notices important tool events such as git push and reminds the agent to update memory.
3. PreCompact writes a non-canonical draft before context compaction.
4. hooks.json.template provides a starting wiring pattern.

Hooks are live only after local runtime configuration and hooks-status or equivalent smoke checks confirm they run. They must not edit wiki/, raw-sources/, shared memory, or canonical memory automatically. Read references/codex-hooks.md.

If an operator adds a local runtime memory layer around these hooks, treat that layer as private, disposable, and outside the vault. Capture, query, dynamic context, promotion, and auto-proposal switches should start disabled. Dynamic context is advisory only: it may suggest evidence candidates, but it never replaces direct source reading and never becomes instructions.

TOWER — Operator Control Tower And Workflow Discipline

Use the Control Tower layer before public releases, branch closeout, or large memory-operator changes.

Recommended read-only checks:

1. release-status — repo identity, branch/upstream, push boundary, staged files, RAW binary risk, and post-push obligations.
2. branch-close — compact handoff with done candidates, remaining candidates, risks, backlog, and verification commands.
3. release-surface-check — public README/hooks/graph/license/attribution visibility.
4. decision-review — candidates for durable routing into shared decisions, wiki synthesis, runbooks, private lessons, or public surface notes.
5. lesson-review — private operational lessons before any promotion from case to pattern/principle.

These reports are advisory by default. decision-review-mark is the only lifecycle write in this layer, and it must be approval-gated and append-only under 12-{agent}/decision-review/. Do not publish private review-state or lesson content. Read references/workflow-discipline.md.

If the operator is tuning agent skill routing, use the optional Routing Feedback Ledger pattern before creating a full trigger eval harness. It records significant branch-level observations with evidence level, causal confidence, routing case type, and runtime/approval metadata, then turns weekly review into action candidates. It is documented as a portable pattern rather than bundled as an automatic recorder. Read references/routing-feedback-ledger.md.

QUALIFY — Retrieval And Context Trials

Use qualification before adopting a new retrieval, context-index, semantic, or OpenViking-style pattern.

Sequence:

1. Build a golden set with real queries, negative cases, forbidden targets, and holdout items.
2. Run the current baseline first: lexical search, existing graph/hybrid tools, and any already-approved query path.
3. Write a gap report that names observed failure modes.
4. Trial only the smallest read-only pattern that addresses one failure mode.
5. Keep safety metrics at zero before any promotion discussion.

Default rule: no measured failure mode, no new memory layer. Read references/memory-qualification.md.

RUNTIME SHADOW — Optional Dynamic Context Review

Use runtime shadow work only when a local operator has built a private runtime layer and wants to test whether dynamic context is worth enabling.

Rules:

1. Keep runtime data outside the vault.
2. Keep dynamic context advisory and off by default.
3. Require reviewed gate evidence plus explicit operator approval before any switch is enabled.
4. Treat promotion as immutable proposal first; canonical apply is a separate approval gate.
5. Run fixed canaries and organic shadow sessions before considering persistent use.

Do not publish local runtime reports, approval manifests, proposals, session drafts, or hook-run records.

MEMORY — Loading Agent Context

Determine the current agent_id before reading private memory.

Recommended roots:

• Shared: 12-shared/
• Codex private: 12-codex/
• Claude private: 12-claude/
• Optional project-local auxiliary layer: agent-memory-{agent}/

Load in this order:

1. 12-{agent}/memory_active.md — current focus and blockers.
2. 12-shared/memory_decisions.md — durable shared conventions.
3. 12-{agent}/memory_corrections.md — last relevant process mistakes before non-trivial tasks.
4. Domain/project files from 12-shared/ based on routing.
5. At most two extra related files unless the user explicitly asks for a broad audit.

Write rules:

• Private operational files go only to the current agent's 12-{agent}/.
• Shared decisions go append-only to 12-shared/memory_decisions.md with attribution.
• Never write one agent's private context into another agent's folder.
• Project-local agent-memory-{agent}/ is auxiliary, not canonical, unless the vault explicitly says otherwise.

RELEASE — Commit/Push Safety

Before committing or pushing a vault:

1. Ensure RAW PDF/DOCX/ZIP files are not staged.
2. Verify provenance links between manifest, converted markdown, and wiki pages.
3. Run wiki lint.
4. Check that agent-private memory isolation is preserved.
5. Confirm git status contains only expected changes.
6. Commit in meaningful groups: tooling/docs, wiki content, provenance/index updates.

Read references/release-safety.md for a concrete policy and command pattern.

OPTIONAL RUNTIME — Advisory Tools

assets/operator/ contains portable, optional helper scripts:

• operation_registry.py — descriptive registry for operator commands and safety posture.
• retrieval_eval.py — keyword retrieval query/replay checks before any semantic/vector decision.
• bridge_health.py — practical bridge report and bridge/storage dashboard.
• skill_repo_audit.py — advisory resolver/skill repository audit.

These tools are inspired by GBrain-style runtime discipline, but they do not introduce a DB, vector layer, MCP runtime, or auto-fix behavior. Read references/operator-runtime.md.

For optional runtime safety gates, shadow sessions, promotion proposals, retention cleanup, and qualification-first context trials, read references/operator-runtime.md and references/memory-qualification.md.

---

Core Rules

1. Explicit only: use this skill only for direct vault/wiki/memory requests.
2. Evidence first: QUERY answers must name the wiki pages or converted sources used.
3. Synthesis by approval: propose durable synthesis when useful; create it after approval or direct instruction.
4. No raw overwrite: never overwrite RAW files with the same name but different hash.
5. No RAW in Git by default: Git should usually contain wiki, converted markdown, provenance, scripts, docs, and routing, not heavy source binaries.
6. Private memory isolation: one agent never reads/writes another agent's private folder unless the user explicitly asks for an audit.
7. Wikilinks: use [[wikilinks]] inside wiki pages; external URLs belong in source/provenance fields when needed.
8. Connectivity: every durable wiki page should be reachable from index.md, a domain MOC, or a related page.
9. Timestamps: update updated: frontmatter on changed wiki pages.
10. No duplication: wiki stores knowledge; memory stores operating context.
11. Quality over quantity: one well-linked synthesis can beat ten isolated summaries.
12. No performative writes: if a read-only answer is sufficient, do not write just to satisfy a rule. Write when it improves future retrieval, traceability, or operation safety.

---

References

• references/wiki-schema.md — wiki page types, frontmatter, provenance fields, INGEST/QUERY/LINT details.
• references/memory-schema.md — shared/private memory roots, load order, routing, self-improvement loop.
• references/release-safety.md — Git/RAW/provenance safety contract.
• references/bridge-health.md — practical bridges between memory layers; not a full ontology.
• references/operator-runtime.md — optional GBrain-inspired registry/retrieval/audit tools.
• references/memory-qualification.md — qualification-first workflow for retrieval/context patterns.
• references/workflow-discipline.md — portable Control Tower, branch close, decision review, and lesson review.
• references/setup.md — first-time setup guide.
• references/graphify.md — optional Graphify-inspired derived graph/retrieval layer; Obsidian markdown remains source of truth.
• references/codex-hooks.md — optional Codex lifecycle hooks; verify runtime support before relying on them.
• assets/vault-CLAUDE.md — drop-in schema file for wiki/CLAUDE.md.
• assets/templates/ — page templates for summary/entity/concept/synthesis/domain pages plus optional MemPalace-style wings/drawers.