memory-comark

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Memory Comark

Basic Memory notes can carry small, safe components written as Comark block directives (

::bm-bars{...}

…

::

). Basic Memory Cloud draws them in Notes, the Wiki, and shared pages. Everywhere else (a local editor, GitHub, an agent's raw read) the same Markdown still reads as an ordinary list, table, or paragraph, so a component never hides content.

Use a component when its shape says more than a sentence or a list would. Keep prose primary: one figure per idea, at most two per section, with a sentence between them that says what the figure shows.

The full vocabulary, every prop, and every data grammar are in references/components.md. Read it before using a component you have not used before.

Basic Memory 笔记可以包含以 Comark 块指令（

::bm-bars{...}

…

::

）编写的小型安全组件。Basic Memory Cloud 会在 Notes、Wiki 和共享页面中绘制这些组件。在其他所有地方（本地编辑器、GitHub、Agent 的原始读取结果），同一份 Markdown 仍会显示为普通列表、表格或段落，因此组件绝不会隐藏内容。

当组件的呈现形式比一句话或列表更能表达信息时，使用组件。应以文字叙述为主：每个想法配一个图形，每节最多两个，并在两个图形之间用一句话说明该图形展示的内容。

完整的组件词汇表、所有 props 和所有数据语法见 references/components.md。使用尚未使用过的组件前，请先阅读该文档。

Project scope

项目范围

If the project is unknown, discover it with

bm_project(command="list")

. Pass a nonempty

project

on every note, folder, context and schema call, even with one project or a qualified

memory://

URL. Use the chosen project's name,

workspace/project

, or external ID;

<project>

below is a placeholder for it. Recent activity also requires

project

. Search accepts

project

for one project,

projects

for selected projects, or

all_projects=True

explicitly. Discovery and bundled manuals need no project. Keep the same scope when following returned paths, paginating, or recovering from a refusal.

如果尚不清楚项目，使用

bm_project(command="list")

发现项目。每次调用笔记、文件夹、上下文和 schema 接口时，都要传入非空

project

，即使只有一个项目或使用带项目限定的

memory://

URL 也是如此。使用所选项目的名称、

workspace/project

或外部 ID；下文的

<project>

是它的占位符。

Pick a component

选择组件

Most notes need only these. The reference has the rest (39 in total).

You want to show	Use
One or a few headline numbers	`bm-stat`
A comparison of a few values	`bm-bars`
A short ranked list	`bm-rank`
A small data table	`bm-table`
Progress toward a whole	`bm-meter`
A trend without axes	`bm-spark`
Steps that drop off	`bm-funnel`
A task list	`bm-check`
Work in lanes (now, next, later)	`bm-kanban`
Events in order	`bm-timeline`
A framed claim or summary	`bm-frame`
A short path ( `a → b → c` )	`bm-flow`
A real graph, sequence, or state machine	a fenced ```mermaid block (not a component)

If nothing fits, write prose or a plain Markdown table. Never invent a component: an unknown name such as

::bm-pie

is not drawn and shows as raw text.

大多数笔记只需要以下组件。参考资料中还有其余组件（共 39 个）。

你想展示的内容	使用
一个或少量关键数字	`bm-stat`
几个数值的对比	`bm-bars`
简短的排名列表	`bm-rank`
小型数据表	`bm-table`
整体完成进度	`bm-meter`
无坐标轴的趋势	`bm-spark`
逐步流失的步骤	`bm-funnel`
任务列表	`bm-check`
按泳道划分的工作（现在、接下来、以后）	`bm-kanban`
按顺序排列的事件	`bm-timeline`
带边框的主张或摘要	`bm-frame`
短路径（ `a → b → c` ）	`bm-flow`
实际的 graph、sequence 或 state machine	一个 ```mermaid 围栏代码块（不是组件）

如果没有合适的组件，请撰写文字或普通 Markdown 表格。切勿虚构组件：未知名称（如

::bm-pie

）不会被绘制，而会显示为原始文本。

Write a component

编写组件

Every component opens with

::bm-name{attributes}

on its own line and closes with

::

on its own line.

markdown

The queue rewrite more than doubled steady-state throughput.

::bm-bars{title="Throughput" caption="Before and after the queue rewrite"}
- Before: 42/s
- **After: 96/s**
::

Rules that matter:

Data goes in the body as Markdown, not in an attribute:
```
- label: value
```
rows, a table for grids. Bold marks the current or chosen row, italic recedes,
```
 — note
```
adds a side note.
Attribute values are double-quoted and cannot contain
"
. There is no escape. Inside a
```
query
```
, quote phrases with single quotes:
```
query="search 'queue rewrite'"
```
.
Task state stays in Markdown. Use
```
- [ ]
```
and
```
- [x]
```
inside
```
bm-check
```
and
```
bm-kanban
```
; people can tick boxes from the rendered note.
Never put HTML, scripts, styles, or classes in a note, and never wrap a component in a code fence (a fenced block stays literal code).
Use only registered props. An unknown attribute produces
```
prop-unknown
```
in a warning frame with the original source and registered props; it is never silently dropped.

A checklist and a board:

markdown

::bm-check{title="Launch"}
- [x] Freeze the schema
- [ ] Write the migration note — due Friday
::

::bm-kanban{title="Roadmap"}

每个组件都以单独一行中的

::bm-name{attributes}

开头，并以单独一行中的

::

结束。

markdown

The queue rewrite more than doubled steady-state throughput.

::bm-bars{title="Throughput" caption="Before and after the queue rewrite"}
- Before: 42/s
- **After: 96/s**
::

重要规则：

数据放在正文中，以 Markdown 形式提供，而不是放在属性中：使用
```
- label: value
```
行，网格数据则使用表格。粗体表示当前或选中的行，斜体表示弱化项，
```
 — note
```
添加旁注。
属性值必须使用双引号，且不能包含
"
。没有转义机制。在
```
query
```
内部，使用单引号包裹短语：
```
query="search 'queue rewrite'"
```
。
任务状态保留在 Markdown 中。 在
```
bm-check
```
和
```
bm-kanban
```
内使用
```
- [ ]
```
和
```
- [x]
```
；读者可以在渲染后的笔记中勾选复选框。
绝不要在笔记中放入 HTML、脚本、样式或 classes，也不要用代码围栏包裹组件（围栏代码块会保持为字面代码）。
仅使用已注册的 props。 未知属性会在警告框中产生
```
prop-unknown
```
，并附带原始源码和已注册 props；绝不会静默忽略。

清单和看板：

markdown

::bm-check{title="Launch"}
- [x] Freeze the schema
- [ ] Write the migration note — due Friday
::

::bm-kanban{title="Roadmap"}

Now

Billing page
Usage emails

Billing page
Usage emails

Partner portal ::

undefined

Partner portal ::

undefined

Live views over the knowledge base

基于知识库的实时视图

A component with a

query

attribute shows current data from the project it lives in. Prefer a live view to a hand-copied number when the note describes its own knowledge base, because copied counts go stale.

markdown

::bm-stat{label="Open decisions" query="notes | where type == decision and status == open | count"}
::

::bm-bars{title="Open decisions by owner" query="notes | where type == decision and status != done | group owner | sort count desc"}
::

::bm-table{title="Due soon" query="notes | where tags contains infra and due < 2026-10-15 | fields title, owner, due | sort due"}
::

::bm-timeline{title="Recent edits" query="activity 7d"}
::

::bm-rank{title="Related notes" query="search 'checksum conflict' | limit 5"}
::

A pipeline reads left to right: a source (

notes

search 'phrase'

activity 7d|30d

), then optional stages in order:

where

group

count

sum field

fields

sort

limit

(1–50). The reference lists every operator and which components accept which shapes.

Shapes that work:

Charts, ranks, and bars need a number per row: add
```
group field
```
,
```
count
```
, or
```
sum field
```
, or use a
```
search
```
source.
Sparks, KPIs, and plots need several rows (
```
group
```
,
```
daily
```
, or
```
search
```
), not a single
```
count
```
.

bm-table
takes
fields
;

bm-timeline

takes

activity

without

daily

;

bm-activity

takes

activity 30d | daily

Semantics to state honestly in the surrounding prose:

```
notes
```
views are exact counts over indexed frontmatter. Search views are ranked and bounded; call them matches, never "all".
```
!=
```
keeps notes that lack the field.
```
group
```
puts notes without the field in a
```
none
```
group.
Frontmatter numbers are stored as text; comparisons and sums treat decimal text as numbers and ignore everything else.

带有

query

属性的组件会显示其所在项目的当前数据。当笔记描述的是它自己的知识库时，应优先使用实时视图，而不是手工复制的数字，因为复制来的计数会过时。

markdown

::bm-stat{label="Open decisions" query="notes | where type == decision and status == open | count"}
::

::bm-bars{title="Open decisions by owner" query="notes | where type == decision and status != done | group owner | sort count desc"}
::

::bm-table{title="Due soon" query="notes | where tags contains infra and due < 2026-10-15 | fields title, owner, due | sort due"}
::

::bm-timeline{title="Recent edits" query="activity 7d"}
::

::bm-rank{title="Related notes" query="search 'checksum conflict' | limit 5"}
::

查询管道从左到右读取：先是一个数据源（

notes

、

search 'phrase'

、

activity 7d|30d

），然后是按顺序排列的可选阶段：

where

、

group

、

count

或

sum field

、

fields

、

sort

、

limit

（1–50）。参考资料列出了每个操作符，以及各组件支持哪些形态。

可用的数据形态：

图表、排名和柱状图要求每行都有一个数字：添加
```
group field
```
、
```
count
```
或
```
sum field
```
，或者使用
```
search
```
数据源。
迷你图、KPI 和图表需要多行数据（
```
group
```
、
```
daily
```
或
```
search
```
），不能只有单个
```
count
```
。

bm-table
使用
fields
；
bm-timeline
使用不带
daily
的
activity
；
bm-activity
使用
activity 30d | daily
。

周边文字中应如实说明以下语义：

```
notes
```
视图是对已建立索引的 frontmatter 所做的精确计数。搜索视图经过排名且数量有上限；应称为“匹配项”，绝不能称为“全部”。
```
!=
```
会保留缺少该字段的笔记。
```
group
```
会将缺少该字段的笔记归入
```
none
```
组。
Frontmatter 中的数字以文本形式存储；比较和求和会将十进制文本视为数字，并忽略其他内容。

Check the rendered result before you quote it

在引用前检查渲染结果

In Basic Memory Cloud,

bm_read(identifier="<note>", view="text", project="<project>")

returns the note as a reader sees it: every component as plain Markdown, with live queries run now. Read it back after writing a live view and confirm the view has rows before you state a number in prose. A query over a field no note has renders an empty view.

Elsewhere, only the browser runs the query, so run the equivalent read yourself (for example

bm_search

with metadata filters; see the memory-metadata-search skill).

A live chart's body is its snapshot: the rows readers see when live data cannot load. A new live view can leave the body empty; people fill it with Freeze snapshot in the editor. If you add snapshot rows yourself, label them as a snapshot in prose and keep them in the chart's row grammar.

在 Basic Memory Cloud 中，

bm_read(identifier="<note>", view="text", project="<project>")

返回读者所看到的笔记：每个组件都呈现为纯 Markdown，并立即运行实时查询。写入实时视图后，将其读回，并在正文中陈述数字之前确认视图中有数据行。对笔记中不存在的字段执行查询时，会渲染为空视图。

在其他地方，只有浏览器会运行查询，因此应自行执行等效读取（例如使用带元数据过滤器的

bm_search

；参见 memory-metadata-search skill）。

实时图表的正文就是它的快照：即实时数据无法加载时读者所看到的行。新建实时视图后，正文可能为空；用户可以在编辑器中使用 Freeze snapshot 填充正文。如果自行添加快照行，请在文字中将其标注为快照，并使其符合图表的行语法。

Edit a note that already has components

编辑已包含组件的笔记

Change one component with
```
bm_edit
```
(
```
find_replace
```
on its directive line or rows). Do not rewrite the whole note to change one value.
The rich editor normalizes formatting when a person edits the note: attribute order changes and YAML blocks come back as JSON. Values survive; do not fight the formatting.
Keep the closing
```
::
```
lines. A block with a body but no close produces
```
directive-unclosed
```
; the opener and YAML props appear in a warning while following Markdown stays visible. Add the close at the intended boundary in source; the editor never guesses it. Standalone leaves with no body remain valid, though new components should use explicit closes.

使用
```
bm_edit
```
修改单个组件（在指令行或数据行上使用
```
find_replace
```
）。不要为了更改一个值而重写整篇笔记。
当人员编辑笔记时，富文本编辑器会规范化格式：属性顺序会变化，YAML 块会重新呈现为 JSON。值会保留下来；不要与这种格式变化对抗。
保留结尾的
```
::
```
行。带有正文却没有结束标记的块会产生
```
directive-unclosed
```
；开头和 YAML props 会显示在警告中，而后续 Markdown 仍然可见。在源码中于预期边界添加结束标记；编辑器绝不会自行猜测。没有任何正文的独立叶节点仍然有效，但新组件应使用明确的结束标记。

When a component shows an error

组件显示错误时

A broken component renders a coded problem and a fix inside its own frame; the rest of the note still renders. In Basic Memory Cloud,

bm_write

and

bm_edit

list these problems under Component problems in their result (they never block the write), so fix them right away with

bm_edit

comark(7)

in the manual (

memory://man/comark(7)

) is a quick reference to the syntax and codes. The codes you will meet most:

Code	Meaning	Fix
`prop-unknown`	A prop the component does not accept	Remove it or use a registered prop from the warning or reference
`directive-unclosed`	A block with a body is missing its close	Add `::` at the intended boundary in Markdown source
`query-measure`	The chart has no number per row	Add `group` , `count` , or `sum` , or use `search`
`query-series`	A trend from one value	Use `group` , `daily` , or `search` with `limit` ≥ 2
`query-escaped-quote`	`\"` inside a query	Use single quotes inside the query
`query-field` / `query-operator`	Bad field name or operator	Fields are `[A-Za-z0-9_-]` with dotted paths; ops are `== != < <= > >= contains`
`query-stage-order`	Stages out of order	`where` , `group` , `count` / `sum` , `fields` , `sort` , `limit`
`chart-body-empty`	No rows in the body	Add `- label: value` rows
`chart-body-number`	A row without a number	Every row needs a numeric value

Unknown props preserve the original directive and data through nearby rich edits. Closed malformed components can use a reviewed agent replacement and undo; missing-close repairs require source editing. Canonical validation and strict export reject malformed source until repaired. Never author internal recovery nodes such as

bm-problem

. Check component names and props against the reference.

损坏的组件会在自己的框内渲染带代码标识的问题及修复方法；笔记的其余部分仍可渲染。在 Basic Memory Cloud 中，

bm_write

和

bm_edit

会在结果中的 Component problems 下列出这些问题（它们不会阻止写入），因此应立即使用

bm_edit

修复。手册中的

comark(7)

（

memory://man/comark(7)

）是语法和错误代码的快速参考。你最常会遇到以下代码：

代码	含义	修复方法
`prop-unknown`	组件不接受某个 prop	删除该属性，或使用警告信息或参考资料中已注册的 prop
`directive-unclosed`	带正文的块缺少结束标记	在 Markdown 源码预期边界处添加 `::`
`query-measure`	图表每行都没有数字	添加 `group` 、 `count` 或 `sum` ，或使用 `search`
`query-series`	趋势只有一个值	使用 `group` 、 `daily` ，或使用带 `limit` ≥ 2 的 `search`
`query-escaped-quote`	`\"` 位于查询内部	在查询内部使用单引号
`query-field` / `query-operator`	字段名或操作符无效	字段必须匹配 `[A-Za-z0-9_-]` ，也可使用点分路径；操作符为 `== != < <= > >= contains`
`query-stage-order`	阶段顺序错误	`where` 、 `group` 、 `count` / `sum` 、 `fields` 、 `sort` 、 `limit`
`chart-body-empty`	正文中没有数据行	添加 `- label: value` 行
`chart-body-number`	某行没有数字	每一行都需要数值

在附近进行富文本编辑时，未知 props 会保留原始指令和数据。格式错误但已闭合的组件可以通过经审查的 Agent 替换并撤销操作来修复；缺少结束标记的修复需要编辑源码。规范验证和严格导出会在修复前拒绝格式错误的源码。切勿编写

bm-problem

等内部恢复节点。请对照参考资料检查组件名称和 props。

Checklist

检查清单

Does a figure beat a sentence here? If not, write the sentence.
Is the component name and every prop in the reference?
Is data in the body as Markdown rows or a table, with no
```
"
```
inside values?
For a live view: does the pipeline give the shape this component needs, and did you check the numbers with a read of your own?
Is there prose around the figure saying what it shows and whether a count is exact or a ranking?

在这里图形是否优于一句话？如果不是，就写一句话。
组件名称和每个 prop 是否都在参考资料中？
数据是否以 Markdown 行或表格形式放在正文中，且值中没有
```
"
```
？
对于实时视图：管道是否提供了该组件所需的数据形态？你是否通过自行读取来检查了数字？
图形周围是否有文字说明其展示的内容，以及计数是精确值还是排名？

memory-comark

Original

Translation

Memory Comark

Memory Comark

Project scope

项目范围

Pick a component

选择组件

Write a component

编写组件

Now

Now

Next

Next

Live views over the knowledge base

基于知识库的实时视图

Check the rendered result before you quote it

在引用前检查渲染结果

Edit a note that already has components

编辑已包含组件的笔记

When a component shows an error

组件显示错误时

Checklist

检查清单