obsidian-project-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian Project Memory

Obsidian项目记忆

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.

为研究项目维护优先文件系统、由Agent驱动的Obsidian知识库。

默认笔记输出语言遵循项目配置的

note_language

；若未配置笔记语言，则默认使用英文。当原文更清晰时，保留技术术语、论文标题和既定文件夹名称的原始形式。仅当用户明确要求时，才切换笔记正文的语言。

当在以下类型的仓库中工作时，优先使用此Skill：

已包含
```
.claude/project-memory/registry.yaml
```
，或
明显属于研究项目且应绑定到Obsidian库的仓库。

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.

使用脚本进行项目状态管理。
使用Agent进行项目理解与合成。
仅将持久研究知识写入精简的库结构中。
无需MCP、API密钥、REST插件或
```
.base
```
工件。
不全局依赖
```
.canvas
```
，但允许文献工作流将
```
Maps/literature.canvas
```
作为默认文献图工件进行维护。
将内部实验总结报告视为
```
Results/Reports/
```
下的面向结果的持久笔记，而非
```
Writing/
```
下的笔记。

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.

仅写入以下项目布局：

text

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

阅读references/SCHEMA.md了解确切结构和笔记角色。

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.

仅将

scripts/project_kb.py

用于低自由度操作，如检测、初始化、同步和生命周期管理：

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"

不要期望脚本理解项目含义。它仅管理状态，不能替代合成工作。

在决定任务属于脚本处理还是必须由Agent驱动时，阅读references/SCRIPT-VS-AGENT.md。

Default workflow

默认工作流

1. Detect and bind

1. 检测与绑定

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.

运行

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

。

如果仓库已绑定，则继续处理现有项目。
如果仓库尚未绑定但属于典型研究项目，则使用
```
project_kb.py bootstrap
```
进行初始化。

如需了解详细生命周期，请阅读references/WORKFLOW.md。

2. Read the minimum context

2. 读取最小上下文

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.

在写入任何内容之前，仅读取最少量的稳定上下文：

```
.claude/project-memory/<project_id>.md
```
```
00-Hub.md
```
```
01-Plan.md
```
若存在，则读取当日的
```
Daily/YYYY-MM-DD.md
```

如果任务涉及项目理解、现有文档或历史结果，请选择性加载更多上下文，参考下文。

3. Classify the knowledge delta

3. 分类知识增量

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.

将当前操作归类到以下一个或多个类别中：

```
knowledge
```
（知识）
```
paper
```
（论文）
```
experiment
```
（实验）
```
result
```
（结果）
```
writing
```
（写作）
```
daily
```
（日常）
```
project-structure
```
（项目结构）

在写入之前，请阅读references/NOTE-ROUTING.md。

4. Follow the default durable research path

4. 遵循默认的持久研究路径

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.

实质性研究工作的默认路径：

```
Papers/
```
-> 提取可复用的想法、基线和项目相关性内容
```
Experiments/
```
-> 将其转化为可测试的假设、操作手册或对照实验方案
```
Results/
```
-> 整理带有证据和解读的稳定发现
```
Results/Reports/
```
-> 当完成完整回顾后，存储某一轮或某一批次的内部实验报告
```
Writing/
```
-> 将持久化结论转化为综述、提案、草稿、幻灯片或反驳笔记

将

Daily/

用作时间记录和暂存区，而非持久研究知识的最终存储位置。

在决定如何推进当前操作时，请阅读references/PAPERS-TO-WRITING.md。

5. Decide whether agent-first synthesis is required

5. 判断是否需要优先使用Agent进行合成

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.

在以下场景中优先使用Agent进行导入/合成：

首次导入现有仓库时，
用户表示知识库为空或缺乏背景信息时，
需要将多个源文档合成为稳定的项目知识时，
项目需要持久化概述、研究问题、实验图谱或结果总结时。

在这些情况下，首先使用Agent读取关键源文件，然后将合成结果写回Obsidian。

如需了解推荐的源文件读取顺序，请阅读references/AGENT-FIRST-IMPORT.md。

6. Write back minimally

6. 最小化写回操作

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.

始终保持写回操作的谨慎性。

至少需要写回以下内容：

当当前操作改变项目状态时，写回当日的
```
Daily/YYYY-MM-DD.md
```
，
仅当近期进展或顶层状态确实发生变化时，才更新
```
00-Hub.md
```
，
当项目状态改变时，更新
```
.claude/project-memory/<project_id>.md
```
。

然后仅写入与类别匹配的持久笔记：

```
knowledge
```
->
```
Knowledge/
```
```
paper
```
->
```
Papers/
```
```
experiment
```
->
```
Experiments/
```
```
result
```
->
```
Results/
```
```
writing
```
->
```
Writing/
```
```
daily
```
->
```
Daily/
```

project-structure

-> 通常为

Knowledge/Project-Overview.md

或

Knowledge/Source-Inventory.md

内部实验轮次报告默认存储路径：

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

当需要稳定格式的笔记时，请阅读references/NOTE-TEMPLATES.md。

Knowledge CRUD rules

知识CRUD规则

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.

审慎地引入新知识；不要将每个新Markdown文件等同于持久笔记。
尽可能为每个持久对象保留一份标准笔记：
- 一份稳定的项目概述，
- 每个实验系列对应一份稳定的实验笔记，
- 每个持久发现对应一份稳定的结果笔记，
- 每篇论文对应一份稳定的论文笔记。
对于新Markdown文件，默认遵循先总结，再归类的原则：
- 仅当文件已稳定且独立时，直接升级为持久笔记，
- 否则合并到现有标准笔记中或暂存到
```
Daily/
```
  。
如果新的持久对象是完整的内部实验报告，则将其存储在
```
Results/Reports/
```
下，并关联对应的
```
Experiments/
```
笔记和标准
```
Results/
```
笔记。

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.

优先进行窄范围查询：
- 宽泛的项目问题 ->
```
00-Hub.md
```
  + 关键
```
Knowledge/
```
  笔记，
- 活跃工作相关问题 ->
```
01-Plan.md
```
  + 当日
```
Daily/
```
  笔记 + 项目记忆，
- 特定实验/结果/论文问题 -> 首先查看匹配的标准笔记，
- 特定内部实验回顾 -> 首先查看
```
Results/Reports/
```
  下的匹配笔记。
仅当答案涉及多个持久源，或阅读标准笔记后仍需依赖仓库材料时，才使用Agent进行合成。

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/
```
.

优先更新现有标准笔记，而非创建同级笔记。
将原始材料视为输入，而非最终的库对象。
允许在
```
Daily/
```
中快速进行追加式记录，但将持久知识存储在
```
Knowledge/
```
、
```
Papers/
```
、
```
Experiments/
```
、
```
Results/
```
、
```
Results/Reports/
```
或
```
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.

默认将“移除”、“删除”或“停止使用”视为归档操作。
仅当用户明确要求永久删除时，才进行清除操作。
归档或清除持久笔记时，修复
```
00-Hub.md
```
、
```
01-Plan.md
```
和明确索引笔记中的直接链接，确保主要工作界面不会指向缺失文件。

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.

不要将整个仓库镜像到库中。
不要生成无实际内容的空文件夹分类或占位笔记。
不要将每个仓库变更都写入新笔记。
不要将每次代码变更都视为知识更新。
除非用户明确要求，否则不要创建
```
.base
```
文件。
不要随意创建
```
.canvas
```
文件；主要的例外是文献工作流中的
```
Maps/literature.canvas
```
。
对于仅涉及工程的操作，优先使用
```
Daily/
```
笔记加项目记忆，除非确实对实验、结果或规划产生影响。
默认将“移除项目知识”视为归档操作；仅当用户明确要求时，才进行永久删除。

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

仅加载所需内容：

```
references/SCHEMA.md
```
- 库结构和笔记角色
```
references/WORKFLOW.md
```
- 检测/初始化/同步/归档工作流
```
references/PAPERS-TO-WRITING.md
```
- 从文献到实验、结果和写作的默认流转流程
```
references/SCRIPT-VS-AGENT.md
```
- 低自由度脚本操作与Agent专属推理的边界
```
references/KNOWLEDGE-CRUD.md
```
- 持久研究知识的创建/读取/更新/删除规则
```
references/NOTE-ROUTING.md
```
- 各类知识的存储路径
```
references/NEW-MD-INGESTION.md
```
- 如何导入新创建的Markdown文件
```
references/AGENT-FIRST-IMPORT.md
```
- 如何通过Agent合成导入现有项目
```
references/NOTE-TEMPLATES.md
```
- 常见笔记类型的轻量格式模板