mcpField
M
Mazarbul

Mazarbul

本地服务
github.com记忆与知识26 天前更新

关于 Mazarbul

Mazarbul 是面向 AI Agent 的本地优先记忆与结构化数据层,以 Go 二进制文件提供命令行工具和 MCP 服务。它结合签名事件日志、混合检索与 Git 同步,让记录可审计并由用户掌控。

主要功能

  1. 01自由文本与结构化记忆
  2. 02向量、全文和图谱混合检索
  3. 03签名追加式事件历史
  4. 04基于 Git 的无冲突同步
  5. 05事实溯源与审计工具

适用场景

  1. 01在 Agent 会话间保留项目背景
  2. 02查询关联实体与事实
  3. 03维护可审计的决策日志
  4. 04在多台设备间同步 Agent 记忆

MCP 相关

Mazarbul 提供 MCP 服务,兼容的 Agent 可通过 `remember`、`recall` 和实体操作等工具存储、查询与回忆记忆。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址,请按项目 README 中的说明安装。

代码仓库
安装包
mcpbmazarbul_v0.2.3_darwin_arm64.mcpb
mcpbmazarbul_v0.2.3_darwin_amd64.mcpb
mcpbmazarbul_v0.2.3_linux_amd64.mcpb
mcpbmazarbul_v0.2.3_linux_arm64.mcpb

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。

详细介绍

Mazarbul

Agent 时代的记录系统。

本地优先、原生支持 Git 的记忆与结构化数据,供 AI Agent 使用。一个 Go 二进制文件。支持 MCP。你的数据永远不会离开你的设备。

License: Apache 2.0 Go 1.26 MCP Local-first Works with Claude Code

Mazarbul:从零开始打造能记住事情的 Agent

什么是 Mazarbul

你的 Agent 患有顺行性遗忘症。它们会忘记会话之间的一切,所以你每次都得重新解释代码库、个人偏好和决策。常见的解决办法并不可靠:CLAUDE.md 容量有限,而且内容会过时;Markdown 知识库不是数据库;云端记忆则是你无法查询、审计或掌控的不透明数据块。

Mazarbul 是 Agent 用来记住事情的地方。它是一个本地二进制文件 maz,任何支持 MCP 的 Agent(Claude Code、Cursor 或你自己的 Agent)都可以与之通信。在底层,它是一个只追加、经过密码学签名的事件日志,并投影到图、向量索引和全文搜索中,还可通过普通 Git 进行同步。每条事实都带有来源。没有任何数据会偷偷发送回家。

它既能存储自由文本事件记忆,也是一个真正的数据库,可供你查询类型化实体、关系和事实。你可以把它看作个人知识图谱、CRM、决策日志和 Agent 记忆,全部放在一个由你掌控的文件中。

它还可以无头运行。一个精简的二进制文件就能提供 CLI 和 MCP 服务,无需另外部署数据库服务,也不需要 UI。因此,任何需要持久化结构化或非结构化数据的场景都可以使用它:通过 MCP 接入的 Agent、调用 maz 的脚本或 cron 任务,或在命令行中使用它的你。Mazarbul 是一个可用于几乎任何场景的本地数据层。

它的不同之处:

  • 事件溯源并带有签名。 每条记忆都是不可变的 ed25519 签名事件。日志是事实来源;索引是可重建的派生数据。内容不会被悄然覆盖。
  • 四层混合检索。 向量相似度、BM25 全文搜索、图遍历和名称嵌入,共同生成一个排序结果,并显示各项评分明细。
  • 原生支持 Git,无冲突。 纯文本 JSONL 可通过任何 Git 远程服务同步。两台设备从设计上就能收敛一致(CRDT),因此并发写入永远不会互相覆盖。
  • 每条事实都有来源记录和审计信息。 maz blame 会显示谁在何时更改了什么,就像针对 Agent 记忆的 git blame。没有其他记忆层将此作为一等功能。
  • 结构化与非结构化兼备。 除了自由文本 remember,还可以定义和查询类型化实体、关系与事实。这是数据库,而不是一堆笔记。
  • 引用你正在使用的工具,而不是复制它们。 你的 Agent 已通过 MCP 连接到 Notion、Linear、Drive 等工具。Mazarbul 会用指针、简短摘要和新鲜度锚点为这些内容建立索引,而不会保存正文,因此检索可以同时涵盖你自己的记忆和实时数据源,且不会产生重复内容。

你的 Agent 是大脑,Mazarbul 是记忆

通过 MCP 调用 Mazarbul 的 Agent(Claude Code、Cursor 或你自己的 Agent)已经是一个强大的模型,因此让它负责推理。它会判断哪些内容值得记住,使用结构化工具(createEntity、relate、fact)写入实体、关系和事实,解决重复项,并根据 recall 和 getContext 返回的内容回答你的问题。Mazarbul 负责存储、索引和回忆,并证明每条记录的来源。这就是为什么 maz init 默认不配置服务端聊天模型:你只需要一个小型本地嵌入模型来进行语义回忆,而不需要第二个 LLM。服务端模型(Anthropic 或本地 Ollama 模型)是可选的额外功能,仅在没有 Agent 参与时才有帮助:被动文件监视、连接器摄取、在普通终端中运行 maz ask,以及后台整合。

安装

curl -fsSL https://raw.githubusercontent.com/mo-cmyk/mazarbul/main/scripts/install.sh | sh

或者使用 Homebrew(macOS 和 Linux):

brew install mo-cmyk/mazarbul/maz

安装程序会验证下载文件的校验和,安装 maz 及其捆绑的引擎库和 man 页面,并设置本地模型提供方(它会安装 Ollama 并拉取语义回忆所需的嵌入模型,除非你使用 --no-ollama 选择退出)。它不会拉取聊天模型:推理由你的 Agent 完成。然后运行 maz init。如果你也希望 Mazarbul 自行推理(无 Agent 参与的摄取、maz ask),为本地模型在安装程序中添加 --with-chat-model,或运行 maz init --provider anthropic --api-key ... 使用远程模型。

MCP Registry / 一键安装包。 每个版本都会为每个平台提供一个 mazarbul_<tag>_<os>_<arch>.mcpb MCP Bundle,Claude Desktop 和其他 MCPB 客户端可直接安装。它会针对你的默认数据目录运行 maz mcp serve,因此能与 CLI 共享记忆(运行一次 maz init 以选择提供方)。每个版本也会以 io.github.mo-cmyk/mazarbul 的名称发布到 MCP 官方注册表,供兼容注册表的客户端和目录收录。

从源代码构建
# Prerequisites: mise (https://mise.jdx.dev), git.
git clone https://github.com/mo-cmyk/mazarbul.git
cd mazarbul
mise install          # provisions Go, golangci-lint, lefthook, vhs, ...
mise run setup        # go mod download + engine lib + hooks
mise run build        # builds ./bin/maz (with sqlite_fts5)
./bin/maz --help

maz 会动态链接一个小型原生图引擎(LadybugDB),通过 rpath 在你的 Go 模块缓存中解析,因此源代码构建的程序可在构建它的机器上运行。若要使用包含引擎的独立可重定位二进制文件,请使用上面的安装程序。

快速入门:从零开始构建 Agent 记忆

# 1. Initialize your Book: pick a data dir; keep the default "no server-side
#    chat model" (your agent reasons) or opt into one. Turn on encryption and
#    init shows a recovery Watchword to save (your only key).
maz init

# 2. Wire it into Claude Code over MCP. --capture records each session passively;
#    --warm-start injects a context brief when a new session begins.
maz connect claude-code --capture --warm-start

# 3. Remember something. Over MCP your agent also writes the entities and
#    relations it sees; with a server-side chat model, maz extracts them too.
maz remember "Frodo Baggins works at Bag End in the Shire as a ring-bearer."

# 4. Recall it. Hybrid search (vector + full-text + graph + name-embedding), scored.
maz recall "where does Frodo work"

就是这样。现在,Claude Code 已有一个指向你的 Book 的 recall 和 remember 工具,它工作的每个会话都会被记住并反馈回来。任何其他 MCP Agent 也可以通过 maz mcp serve 以相同方式连接。

工作原理

事件日志是真实数据的来源。其他所有内容都是可重建的投影。

flowchart TD
    A["maz remember / relate / fact<br/>(CLI, MCP, ambient hooks)"] --> B

    subgraph SOT["Source of truth"]
      B["Signed, append-only JSONL event log<br/>(ed25519 author on every event)"]
    end

    B --> D{{"Dispatcher<br/>(the only writer to the projections)"}}

    subgraph PROJ["Rebuildable projections (maz rebuild)"]
      direction LR
      E["SQLite<br/>relations + facts"]
      F["LadybugDB<br/>graph traversal"]
      G["sqlite-vec<br/>semantic recall"]
      H["FTS5<br/>keyword / BM25"]
    end

    D --> E & F & G & H

    E & F & G & H --> I["Hybrid recall<br/>(4 lanes, fused + scored)"]

    I --> J["Surfaces<br/>MCP (agents) | CLI / TUI (humans)"]

    B -. "seal + push (plaintext JSONL<br/>+ rendered markdown tree)" .-> K[("Any git remote<br/>conflict-free / CRDT")]
    K -. "pull (no LLM re-extraction)" .-> B

由于日志仅追加,且每个事件都不可变并经过签名,因此同步同一日志的两台设备会收敛到字节完全相同的状态。这里没有“最后写入者获胜”式的覆盖。如果任何索引损坏,maz rebuild 都会根据日志重建全部四个索引。

为你的 Agent 打造的数据库,而非一堆笔记

这就是它的核心。Mazarbul 既存储自由文本,也存储结构化数据,并允许你查询两者。

# Define a typed entity kind and a custom relation, on the fly. An agent can do
# this over MCP too; the ontology is data, so it syncs and versions like the rest.
maz schema kinds add artifact --display-name "Artifact" --description "An object of power"
maz schema predicates add bears --description "carries an object of power"

# Preview what defineEntityKind would do before committing (mint / collapse / supersede):
maz schema preview kind artifact --description "An object of power"

# Mint structured entities with typed properties, then wire the graph by name.
# relate takes names or ULIDs and requires both endpoints to already exist.
maz entity create person "Frodo Baggins"
maz entity create artifact "The One Ring" --attributes '{"forged_in":"Mount Doom","power":"invisibility"}'
maz relate "Frodo Baggins" bears "The One Ring"

# Read it back: typed kind, typed properties, provenance, and the new relation.
maz get "The One Ring"
maz neighbors "Frodo Baggins"

# Assert a scalar fact with history. Later writes supersede the value but keep the
# old one, so you can still ask where the Ring-bearer was earlier in the journey.
maz fact set "Frodo Baggins" location "Rivendell"
maz fact get "Frodo Baggins"

# Close a fact that stopped being true (keeps history), or hard-delete one outright.
maz fact retract "Frodo Baggins" location   # slot reads empty after; history preserved
maz forget facts/01ARZ3NDEKTSV4RRFFQ69G5FAV  # remove a fact row entirely

# Query the lot with one hybrid recall over structured data and free text, and
# pin the view to a point in time (valid-time).
maz recall "who carries the ring"
maz recall "who carries the ring" --at 2026-01-01T00:00:00Z   # facts as they were valid on Jan 1

定义类型化类别、创建实体并查询该实体

纯 Markdown 无法查询、联接或跟踪变更。纯向量搜索无法关联不同文档中的事实。Mazarbul 提供可查询图中的类型化实体和关系,以及自由文本事件,并在一次回忆中将两者融合。

你可以做什么

Mazarbul 是一个通用的无头数据层和权威记录系统。同一套基本构件可以变成多种工具:

  • Agent 记忆。 默认选项。remember 事实,在不同会话中 recall 这些事实。无需再向每个 Agent 反复解释你的项目。
  • 笔记和知识库。 maz doc import ~/notes 会导入你的 Markdown;维基链接会解析为实体;maz doc log 和 maz doc diff 会为每篇笔记保留历史记录。
  • 个人 CRM。 人员、组织以及它们之间的关系(works_at、reports_to、introduced_by)。记录你与某人相识的过程和原因,而不只是姓名。
  • 决策日志 / ADR。 采用仅追加设计,并带有取代链接。决策背后的推理会一直保留并可供查询,即使你早已忘记。
  • 知识图谱。 定义领域类型和谓词,安装架构包,并遍历结果。
  • 团队大脑。 一个共享且端到端加密的作用域,让整个团队的 Agent 都能使用同一份记忆。
草稿暂存:提交前先暂存

有时,你想先记录内容,但不希望它立即成为永久记忆的一部分。使用 --scope draft 写入,内容会进入私有暂存区;在你决定如何处理之前,它不会对 recall、get 和其他任何读取动词可见:

# Stage privately. Nothing in recall or getContext sees this yet.
maz remember "rough notes from the Prancing Pony meeting" --scope draft

# Review what is staged.
maz scope draft list            # episodes, entities, and relations in staging
maz scope draft diff            # compare draft against your personal set side by side

# Promote into personal memory (now recall-able and sync-able).
maz scope draft promote episodes/01ARZ3NDEKTSV4RRFFQ69G5FAV

# Or throw it away. The audit event is appended; the projection is cleaned up.
maz scope draft discard episodes/01ARZ3NDEKTSV4RRFFQ69G5FAV

提升始终以 personal(或 project)为目标。按设计,系统会拒绝直接提升到共享的 team 作用域——未经审核的草稿数据不应在没有明确团队写入操作的情况下进入共享作用域。丢弃操作会删除该事件及其创建的所有草稿实体;事件日志本身仅允许追加,因此审计记录会得到保留。

命名的回忆快捷方式

保存一次查询,需要时随时重放:

maz saved add standup --query "daily standup Berlin team" --limit 5
maz saved list                          # all saved queries
maz saved show standup                  # stored parameters
maz saved recall standup                # run it through the live recall pipeline
maz saved remove standup

已保存的查询位于你的 Book 的 config.toml 中的 [saved_recalls] 下。重放查询时始终会访问实时索引,因此随着新事件的到来,结果也会不断变化。

构建自己的技能和本体

预设是供 Agent 使用的技能:一个架构包(实体类型和谓词),再加上一个 instructions.md,用于指导 Agent 何时以及如何使用它们。你可以安装预设、编写自己的预设,或发布预设供他人使用。

maz install schema-org-core           # built-in pack: common schema.org types
maz install business-de               # built-in pack: German business + legal types
maz preset install agent-memory       # teaches an agent when to reach for memory
maz preset install second-brain       # life-graph: people, projects, notes, topics
maz preset install decision-trace     # decision provenance: decisions, insights, principles
maz preset install github.com/you/your-preset   # install a preset from any git repo
maz preset package ./my-preset        # validate + print a checksum to publish

安装 second-brain 后,它会创建 brain:Person、brain:Project、brain:Note 和 brain:Topic 类型,并添加 collaborates_on、tagged_with 和 inspired_by 等关系。添加几篇笔记后,试着进行一次回忆,看看图谱如何组织这些笔记。decision-trace 会创建 decision、insight 和 principle 类型,并通过一等可追溯性边将它们连接起来。

使用 maz schema kinds add / maz schema predicates add 临时定义类型,或让 Agent 通过 MCP 使用 defineEntityKind / definePredicate 来定义。写入前,使用 maz schema preview kind <name> 查看计划(新建 / 合并到 / 取代)。本体是数据,不是代码,因此它会像其他所有内容一样同步和版本化。

接入现有工具

Mazarbul 能从你的数据现有的存放位置接入数据。

# Import an existing markdown / Obsidian vault. Wikilinks become entities;
# bodies become recall-able. Idempotent, so re-running skips unchanged files.
maz doc import ~/ObsidianVault

# Or point Mazarbul's vault straight at your Obsidian folder (it only ever writes
# documents it owns) and edit notes in Obsidian as usual.
maz config set vault.path ~/ObsidianVault

# Render an entity neighborhood as an Obsidian-openable canvas.
maz doc canvas "Frodo Baggins"

# Pull in your other sources. Connectors ingest untrusted external content, so
# the target scope needs encryption enabled first (maz doctor sets it up).
maz source connect local-git --repo .              # your repo's commit history
maz source import claude-chats ~/Downloads/export.zip   # your Claude.ai exports

正在导入 Markdown 知识库;维基链接会解析为实体

这就是“Karpathy 风格”的外部记忆(Agent 编译一份持久、互联的知识库,而不是针对每次查询重新推导所有内容),并补足了 Markdown 维基方案所欠缺的部分:类型化查询层、自动实体图谱、来源信息,以及不会造成损坏的同步。

引用实时来源,而不是复制它们

导入会把数据复制进来。另一种方式则恰恰相反。你的 Agent 已通过 MCP 连接到实际承载你工作内容的工具:Notion、Linear、Granola、Google Drive、GitHub。Mazarbul 不保存这些工具的任何令牌,也绝不会自行获取它们的数据,而是为其建立索引。

Agent 从这些工具之一读取某个条目后,只需调用一次 captureExternal,即可记录指向该条目的指针、Agent 自己撰写的简短摘要,以及一个新鲜度锚点(内容哈希加获取时间)。正文永远不会进入 Mazarbul。随后,这份摘要会与其他所有记忆一起在 recall 中搜索到,而每条基于实时来源的命中结果都会附带内联新鲜度判定和外部来源标记:

recall "the Q3 launch plan"
  Q3 launch: connector wave ships first, then the public install path.
    source: notion   freshness: fresh (fetched 2h ago)   trust: proposed

当某条命中变为 stale(超过该连接器的新鲜度期限)时,Agent 会重新获取实时条目并再次捕获,因此索引始终与真实数据源保持一致。由于其来源链属于外部内容,而非用户撰写,这些条目会被标记为 proposed,即不受信任:它们可搜索、可排序,但会明确标示为来自其他来源的摘要,而不是你所断言的内容。请参阅 agent-docs/external-references.md。

结果是,你可以在同一个地方同时搜索自己的记忆和实时工具,无需维护第二个需要保持同步的存储。

它就是 git

你的记忆以纯文本 JSONL 和渲染后的 Markdown 目录树形式存储在普通的 git 仓库中。你可以使用语义化、感知实体的命令检查,也可以使用你熟悉的 git。

# Seal local memory into signed chunks and push to your git remote.
maz sync push

# Browse it semantically, from anywhere:
maz diff HEAD~5..HEAD         # what changed: entities added, relations superseded
maz diff --kind person --operation changed --format json   # changed person entities as JSON
maz blame "Frodo Baggins"     # who changed this entity, and when
maz changelog                 # per-push summaries, newest first

# Or clone the synced repo and use plain git. It is JSONL plus a rendered markdown
# tree, so log, diff, and blame all just work on it:
git clone <your-remote> memory && cd memory
git log --stat
git blame rendered/by-uid/<...>.md   # line-level provenance, in plain git

maz diff 还支持 --predicate 和 --operation 后置筛选器。JSON 输出(--format json)会在条目旁提供 filtered 计数和 active_filters 映射,因此脚本无需解析文本说明即可断言发生了哪些变化。

批量导入和重新生成嵌入

更换机器、从备份恢复,或切换嵌入模型?两个命令即可完成:

# Bulk-load a JSONL snapshot exported with "maz export".
maz load backup.ndjson                    # append every event (default)
maz load backup.ndjson --mode merge       # skip events whose UID already exists (idempotent)
maz load backup.ndjson --dry-run          # parse + validate, report counts, write nothing

# After switching embedding models, re-embed every episode.
maz reindex --reembed                     # drop episodes_vec and rebuild it
maz reindex --reembed --dry-run           # count what would be re-embedded first

maz load 会输出 {mode, source, total, appended, skipped, invalid, dryRun}。合并模式跳过重复 UID 时会触发警告 MAZ-LOAD-001;行格式错误时会触发 MAZ-LOAD-002。批次操作是原子的:要么所有有效事件都写入,要么一个也不写入。maz reindex --reembed 需要配置嵌入器(maz init --embed=ollama);其他三个派生存储(SQLite、图、FTS5)不受影响。

maz rebuild 和 maz reindex --reembed 都可以在守护进程运行时执行。 无需运行 maz daemon stop。守护进程运行时,CLI 会通过管理 HTTP 接口(POST /admin/v1/rebuild、POST /admin/v1/reindex)路由这些操作;该接口仅通过 Unix 套接字开放,不通过 TCP 开放。守护进程会在临时目录中构建影子投影,在短暂的切换窗口(数秒)内暂停服务,将新索引重命名到位,然后通过同一套接字恢复服务。重新连接的 maz mcp serve 代理会掩盖读取流量所遇到的切换窗口;正在进行中的写入会干净地失败,可以重试。守护进程运行时无法使用 maz reindex --dry-run(它需要进程内的存储访问权限)。maz preset install、maz preset uninstall、maz load 和 maz schema 别名操作也通过同一仅限套接字访问的 /admin/ 接口,将特权写入路由到运行中的守护进程。

maz 同步日志、语义差异,以及 git 跟踪目录树中按实体显示的归因

通过 git 同步的 Markdown 知识库在并发写入时会相互覆盖。Mazarbul 的日志在设计上不会产生冲突,因此两台机器同时推送时会自动收敛,而不是互相覆盖。对于不受信任的主机,可启用按范围加密(XChaCha20-Poly1305),这样仓库中只会存放密封后的密文。

为什么选择 Mazarbul

你可能已经在用其中一种方式了。Mazarbul 能为你带来以下不同之处。

  • Obsidian + Claude Code + git。 你会得到彼此隔离的 Markdown 文件、手动链接、无法查询或联结的内容、并发写入时会损坏的 git 同步,以及只有你手动强制执行时才有的溯源信息。Mazarbul 保留原生支持 git 的纯文本,并添加类型化查询层、自动实体图、无冲突合并,以及每条事实的溯源信息。
  • Agent 记忆库(mem0、Letta、agentmemory)。 向量存储、云 API,或让你受制于其中的框架;记忆是不透明的、由大模型重写的内容,没有溯源或审计。Mazarbul 是本地的,采用四层架构和事件溯源,每条事实都会注明来源且可审计。
  • 键值或向量存储、ChatGPT / Claude 内置记忆。 内容不透明、受云端限制,没有架构、关系、查询或审计功能,并且按产品彼此隔离。Mazarbul 是由你掌控的记录系统,可供你查询、穿越时间回溯,并迁移。
Mazarbul向量记忆(mem0、...)Obsidian + git + Agent内置云端记忆
完全在本地运行,无需账户是部分支持是否
真实数据由你掌控已签名事件日志云端 / 向量内容Markdown 文件供应商云端
每条事实均可溯源 + 审计是否手动处理否
类型化查询 + 图图 + 向量 + FTS向量(+ 可选图)否否
多设备间无冲突的 git 同步是不适用覆盖不适用
时间回溯(有效时间)是否否否
原生支持任何 Agent 的 MCP是SDK / REST通过插件仅限供应商
共享的加密团队范围是云端套餐手动处理否

一句话概括其优势:Agent 既需要自由文本,也需要结构化数据,而能将两者结合的系统(GraphRAG、Zep)都在云端运行。Mazarbul 将这种组合带到你拥有的单个文件中,并提供其他产品都不具备的溯源功能和原生支持 git 的同步。

与 Claude Code 和任何 MCP Agent 配合使用

maz connect claude-code               # register over MCP (also: claude-desktop, ...)
maz connect claude-code --capture --warm-start   # passive capture + session warm-start
maz connect                           # show the live detection table for every client

连接后,Claude Code 会基于你的 Book 工作,遍历图谱来关联事实,而不只是检索文本。同一份记忆既能为无头模式下的一次性 claude -p 调用提供答案,也能用于实时交互会话,无需工具列表或提示词:

两个 Claude Code 会话,一个处于无头模式,一个处于交互模式,它们遍历记忆图谱来回答谁佩戴着魔戒,以及谁背叛了护戒同盟

对于 Cursor、自定义 Agent 或任何其他 MCP 客户端,可直接运行服务:

maz mcp serve            # stdio (default)
maz mcp serve --http     # streamable HTTP at 127.0.0.1:7842
maz mcp serve --unix     # Unix socket

连接的 Agent 会获得一组简洁的工具:remember、recall、forget、relate、get、neighbors、relations、entities、query、createEntity、defineEntityKind、getContext、getEntityContext(针对单个实体、按令牌预算整理的档案)、agentFeedback 等。团队中的人员可通过命令行中的 maz 或其 TUI 使用完全相同的数据。

面向用户:TUI、实时监视和 Agent Mirror

同一份记忆还提供丰富的交互界面,无需 Agent:

maz self                       # the Agent Mirror: what Mazarbul knows about you
maz recall "the ring" --tui    # interactive master-detail recall browser (recall → get → neighbors)
maz doc browse                 # two-pane TUI over your markdown vault
maz watch                      # live dashboard: events, jobs, embedding, and sync

maz 学习使用方式

这是 Omnigraph 对等化进程的核心。每当 Agent 遇到令人困惑的结果、错误答案,或值得保留的来之不易的规则时,都可以记录下这次摩擦。反复出现的摩擦会自动提炼为一句话,并提升至 ## Known gotchas & lessons 部分,附加在每个新 MCP 会话指令的末尾——因此,每个连接的 Agent 都能获得不断演进的指导,无需任何人工整理。

# Record a durable lesson from the CLI (agents use the agentFeedback MCP tool).
maz feedback record --category lesson --severity medium \
  --surface recall \
  --summary "recall missed an exact name" \
  --rule "prefer get when you already hold the exact name"

# See what is currently promoted into every session's instructions.
maz feedback gotchas

# Inspect the raw triage queue.
maz feedback list --category confusing

# Pin a cluster (always included, even if the cap fills up).
maz feedback pin "lesson|recall|prefer get exact name"

# Suppress a cluster from promotion.
maz feedback veto "lesson|recall|prefer get exact name"

# Edit the distilled rule text.
maz feedback edit "lesson|recall|prefer get exact name" --rule "use get for exact-name lookups"

# Export an allowlist-redacted diagnostic (safe to share; no user memory ever leaves).
maz feedback export --format md -o feedback.md

提升阈值:某个簇重复出现 3 次后会提升;若其观察到的最高严重程度为 high,则重复 2 次即可提升。固定的簇不受 8 条上限限制;被否决的簇永远不会出现。每次审核都会追加一条经过审计的事件——绝不会删除任何内容。导出会剔除所有用户记忆、主体 ID、簇密钥和团队范围:仅导出 {id, ts, category, severity, surface, summary, detail, keywords, version, activePreset}。完整设计请参阅 agent-docs/feedback-loop.md。

输出格式与脚本

每个读取动词都支持 --output(或 MAZ_OUTPUT 环境变量):

maz recall "Frodo" --output json          # single JSON document
maz entities --kind person --output ndjson  # one JSON object per line (stream-friendly)
maz entities --kind person --output csv     # CSV with a header row (cut/awk/spreadsheet)
maz entities --kind person --output kv      # key: value lines, blank between records (grep-friendly)

别名:table = text,jsonl = ndjson。在 Book 配置中设置持久默认值:

maz config set output.default_format json

配置项在优先级链中位于 MAZ_OUTPUT 和 TTY 启发式判断之间,因此脚本会自动获得 JSON,而交互式会话仍会显示表格。

文档

托管文档网站即将推出。

贡献

许可证

Mazarbul 采用 Apache License 2.0 许可。完整条款请参阅 LICENSE,署名信息请参阅 NOTICE。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。