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:

text

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

Read 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:

bash

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 when deciding whether a task belongs in the script or must stay agent-driven.

Default workflow

1. Detect and bind

Run

scripts/project_kb.py detect --cwd "$PWD"

If the repo is already bound, continue with the existing project.
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.

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 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 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 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

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 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

obsidian-project-memory

NPX Install

Tags

SKILL.md Content