obsidian-project-memory

Obsidian Project Memory

Maintain a filesystem-first, agent-driven Obsidian knowledge base for a research project.

Default note output language follows the project's configured note_language; if no note language is configured, default to English. Keep technical terms, paper titles, and established folder names in their original form when that is clearer. Only switch note prose to another language when the user explicitly asks.

Prefer this skill when working inside a repository that:

• already contains .claude/project-memory/registry.yaml, or
• clearly looks like a research project and should be bound to an Obsidian vault.

Core principles

• Use scripts for project state management.
• Use agents for project understanding and synthesis.
• Write only durable research knowledge into a small vault structure.
• Do not require MCP, API keys, REST plugins, or .base artifacts.
• Do not depend on .canvas globally, but allow literature workflows to maintain Maps/literature.canvas as a default literature graph artifact.
• Treat internal experiment summary reports as durable result-facing notes under Results/Reports/, not as Writing/ notes.

Default vault structure

Write into this project layout only:

Research/{project-slug}/
  00-Hub.md
  01-Plan.md
  Knowledge/
  Papers/
  Experiments/
  Results/
    Reports/
  Writing/
  Daily/
  Archive/

Read [references/SCHEMA.md](references/SCHEMA.md) for the exact structure and note roles.

Deterministic helper script

Use scripts/project_kb.py only for low-freedom operations such as detect, bootstrap, sync, and lifecycle management:

python3 scripts/project_kb.py detect --cwd "$PWD"
python3 scripts/project_kb.py bootstrap --cwd "$PWD" --vault-path "$OBSIDIAN_VAULT_PATH"
python3 scripts/project_kb.py sync --cwd "$PWD" --scope auto
python3 scripts/project_kb.py lifecycle --cwd "$PWD" --mode archive
python3 scripts/project_kb.py query-context --cwd "$PWD" --kind broad
python3 scripts/project_kb.py query-context --cwd "$PWD" --kind experiment --query freezing
python3 scripts/project_kb.py find-canonical-note --cwd "$PWD" --kind experiment --query freezing
python3 scripts/project_kb.py note-lifecycle --cwd "$PWD" --mode archive --note "Results/Old-Result.md"

Do not expect the script to understand project meaning. It manages state; it does not replace synthesis.

Read [references/SCRIPT-VS-AGENT.md](references/SCRIPT-VS-AGENT.md) when deciding whether a task belongs in the script or must stay agent-driven.

Default workflow

1. Detect and bind

1. Run scripts/project_kb.py detect --cwd "$PWD".
2. If the repo is already bound, continue with the existing project.
3. If the repo is not yet bound but is a strong research-project candidate, bootstrap it with project_kb.py bootstrap.

For the detailed lifecycle, read [references/WORKFLOW.md](references/WORKFLOW.md).

2. Read the minimum context

Before writing anything, read only the minimum stable context:

• .claude/project-memory/<project_id>.md
• 00-Hub.md
• 01-Plan.md
• today's Daily/YYYY-MM-DD.md if it exists

If the task is about project understanding, existing docs, or historical results, load more context selectively using the references below.

3. Classify the knowledge delta

Route the current turn into one or more of these buckets:

• knowledge
• paper
• experiment
• result
• writing
• daily
• project-structure

Read [references/NOTE-ROUTING.md](references/NOTE-ROUTING.md) before writing.

4. Follow the default durable research path

Default path for substantive research work:

• Papers/ -> extract reusable ideas, baselines, and project relevance
• Experiments/ -> turn those into testable hypotheses, runbooks, or ablations
• Results/ -> promote stable findings with evidence and interpretation
• Results/Reports/ -> store one round or one batch's internal experiment report when a complete retrospective has been written
• Writing/ -> externalize durable claims into reviews, proposals, drafts, slides, or rebuttal notes

Use Daily/ as chronology and staging, not the final home for durable research knowledge.

Read [references/PAPERS-TO-WRITING.md](references/PAPERS-TO-WRITING.md) when deciding how a turn should advance along this path.

5. Decide whether agent-first synthesis is required

Use agent-first import/synthesis when:

• importing an existing repository for the first time,
• the user says the knowledge base is empty or lacks background,
• multiple source documents must be synthesized into stable project knowledge,
• the project needs a durable overview, research questions, experiment map, or results summary.

In these cases, first use an agent to read key sources, then write the synthesized result back into Obsidian.

Read [references/AGENT-FIRST-IMPORT.md](references/AGENT-FIRST-IMPORT.md) for the recommended source-reading order.

6. Write back minimally

Always keep write-back conservative.

Write back at least:

• today's Daily/YYYY-MM-DD.md when this turn changes project state,
• 00-Hub.md only when recent progress or top-level status truly changes,
• .claude/project-memory/<project_id>.md when project state changes.

Then write only the durable note that matches the bucket:

• knowledge -> Knowledge/
• paper -> Papers/
• experiment -> Experiments/
• result -> Results/
• writing -> Writing/
• daily -> Daily/
• project-structure -> usually Knowledge/Project-Overview.md or Knowledge/Source-Inventory.md

Internal experiment round reports should default to:

• Results/Reports/YYYY-MM-DD--{experiment-line}--r{round}--{purpose}.md

Read [references/NOTE-TEMPLATES.md](references/NOTE-TEMPLATES.md) when a note needs a stable shape.

Knowledge CRUD rules

Treat the vault as a small set of canonical notes plus supporting daily context.

Create

• Ingest new knowledge deliberately; do not equate every new Markdown file with a durable note.
• Keep one canonical note per durable object whenever possible:
• one stable project overview,
• one stable experiment note per experiment line,
• one stable result note per durable finding,
• one stable paper note per paper.
• For new Markdown files, default to summarize first, then route:
• promote directly only when the file is already stable and self-contained,
• otherwise merge into an existing canonical note or stage it in Daily/.
• If the new durable object is a full internal experiment report, store it under Results/Reports/ and link the matching Experiments/ and canonical Results/ notes.

Read

• Query narrowly first:
• broad project questions -> 00-Hub.md + key Knowledge/ notes,
• active work questions -> 01-Plan.md + today's Daily/ + project memory,
• specific experiment/result/paper questions -> the matching canonical note first,
• specific internal experiment retrospective -> the matching note in Results/Reports/ first.
• Use agent synthesis only when the answer spans multiple durable sources or still depends on repo material after reading canonical notes.

Update

• Prefer updating an existing canonical note over creating a sibling note.
• Treat raw material as input, not as a final vault object.
• Allow fast append-only logging in Daily/, but keep durable knowledge in Knowledge/, Papers/, Experiments/, Results/, Results/Reports/, or Writing/.

Delete

• Treat “remove”, “delete”, or “stop using” as archive by default.
• Purge only when the user explicitly asks for permanent deletion.
• When archiving or purging a durable note, repair direct links in 00-Hub.md, 01-Plan.md, and explicit index notes so the main working surface does not point to missing files.

Safety rules

• Do not mirror the whole repository into the vault.
• Do not generate empty folder taxonomies or placeholder notes without real content.
• Do not write every repo delta into a new note.
• Do not treat every code change as a knowledge update.
• Do not create .base files unless the user explicitly asks for them.
• Do not create arbitrary .canvas sprawl; the main default exception is Maps/literature.canvas for literature workflows.
• For engineering-only turns, prefer Daily/ plus project memory unless there is a real experiment, result, or planning impact.
• Treat “remove project knowledge” as archive by default; purge only when the user explicitly asks for permanent deletion.

Reference files

Load only what is needed:

• references/SCHEMA.md - vault structure and note roles
• references/WORKFLOW.md - detect/bootstrap/sync/archive workflow
• references/PAPERS-TO-WRITING.md - default handoff from literature to experiments, results, and writing
• references/SCRIPT-VS-AGENT.md - boundary between low-freedom script operations and agent-only reasoning
• references/KNOWLEDGE-CRUD.md - create/read/update/delete rules for durable research knowledge
• references/NOTE-ROUTING.md - where each kind of knowledge should go
• references/NEW-MD-INGESTION.md - how to ingest a newly created Markdown file
• references/AGENT-FIRST-IMPORT.md - how to import an existing project with agent synthesis
• references/NOTE-TEMPLATES.md - lightweight note shapes for common note types