Skip to main content
Glama

听记

在 Mac 上全天听你说话的小工具。没人说话的时候什么都不留;有人说话就转成逐句原文,按事情整理成摘要、待办和项目。Claude Code 这类 Agent 可以通过 MCP 直接读这些记录。

思路来自 OPPO 的「心力球」:挂在身上全天录音,自动按事情整理。听记把这套做法搬到了电脑上:不用另买设备,数据都在自己电脑上,原话全部保留,还能接给自己的 Agent。

今日时间线

它会做什么

  • 全天听,没人说话不留:麦克风每分钟交一片,本机做人声检测(Silero VAD),没人说话的分片直接删掉。

  • 逐句原文:有人声的部分送去转写(阿里云百炼 Fun-ASR),同时分说话人;本机声纹模型(3D-Speaker CAM++)认出哪句是你说的,标成「我」,其余的标「其他人」。

  • 按事情切:两段话隔开 5 分钟以上一定分开,同一段里再按话题切成一件件事。每件事有分类、标题、摘要、要点、待办、决定、值得记住的事和重要度,零碎小事只留一行。

  • 项目:同一件事聊了好几天,会自动串成一条线,写明现在到哪一步、有什么风险、下次该追问什么、谁答应过什么。

  • 每日总结:每天 23:30 以后,按上午、下午、晚上写一份当天的总结。

  • 觉察:每周日晚上,只看「我」说过的话,找出两三个沟通和做事上的习惯,每条带原话依据和下次可以怎么做。

  • 电脑放声音时自动暂停:每秒看一次哪个程序在出声。抖音、浏览器、播放器在放视频,就先停麦克风,声音停 2 秒后接着录。微信、企业微信、飞书、腾讯会议、钉钉、Zoom、FaceTime 通话,以及闪电说、Typeless 这类语音输入出声,不会暂停。

  • 时间线网页:浏览器打开 http://127.0.0.1:7788/ ,有今日、项目、觉察、搜索四页。点开一件事能看逐句原文,点某一句就从那里开始播放录音。网页只对本机开放。

  • 导入 iPhone 语音备忘录:手机上录的备忘录通过 iCloud 同步到 Mac 后,一条命令导进来,和电脑上录的放在一起整理。

截图里的人和事都是编的示例,见下面的「先看效果」。

Related MCP server: shyn

给 Agent 用:MCP

装好以后注册一个 MCP(见「安装」第 3 步),Agent 就能回答这类问题:

  • 「我昨天答应了谁什么?」

  • 「把上周聊定价的原话找出来。」

  • 「双十一投放那件事现在到哪一步了?下次见面该问什么?」

工具

做什么

list_records

一段时间里的全时记(自动切出来的事,E 开头)和随口记(N 开头)

get_record

按编号取一件事的全部字段,可带逐句原文;P 开头是项目

get_transcript

逐句原文,带时间和说话人,不管有没有整理成事件

search

在原话、事件摘要、随口记里搜关键词

todos

最近几天冒出来的待办和承诺

list_projects / get_project

项目列表;一个项目的现状、风险、该追问的问题、承诺和时间线

day_summary

某一天的总结

insights

每周的觉察

memories

从各件事里抽出来值得长期记住的事实,带出处

recorder_status

现在在不在录、整理到几点了

还没处理完的时间段,结果里会写明「整理到几点」,Agent 不会把「还在转写」当成「没有记录」。

安装

需要:

  • macOS 15 或更高

  • 一个麦克风:MacBook、iMac 自带;Mac mini、Mac Studio 要接外置麦克风或耳机

  • Homebrew 装的 ffmpeg、Python 3.11 或更高、Xcode 命令行工具(用来编译菜单栏的录音开关)

  • 两个 API key:阿里云百炼(Fun-ASR 转写)和 DeepSeek(整理)

brew install ffmpeg python@3.13
xcode-select --install        # 装过就跳过
git clone https://github.com/Biancuihuo/tingji.git
cd tingji
./install.sh

install.sh 会依次:建 Python 环境(仓库里的 .venv)、下载两个模型(约 28 MB)、问你两个 API key(存成权限 600 的 secrets.json)、编译并安装菜单栏录音开关、用 launchd 启动后台处理和时间线网页。三样都开机自启。

装完以后:

1. 允许麦克风。 菜单栏出现波形图标就是在录。第一次会弹出麦克风权限,点「允许」。

2. 让它认出你。 对着电脑一个人说 30 秒左右的话,等一两分钟,然后:

.venv/bin/tingji pieces                 # 找到刚才那段的编号
.venv/bin/tingji enroll --piece 编号     # 记下你的声纹
.venv/bin/tingji relabel                # 把已有的句子重新认一遍

不注册声纹也能用,只是所有话都会标成「其他人」,也做不了觉察。离电脑远时说的话如果认不出来,可以再加几个样本,最多留 12 个。

3. 接到 Claude Code。

claude mcp add tingji -s user -- "$PWD/.venv/bin/tingji-mcp"

新开一个会话就能用。其他支持 MCP 的客户端,命令填 仓库路径/.venv/bin/tingji-mcp。

先看效果

不录音、不填 key,也能先看看时间线是什么样:

./install.sh --python-only      # 问 key 时直接回车跳过
.venv/bin/python scripts/demo.py

然后在浏览器打开 http://127.0.0.1:7799/ 。示例数据放在仓库里的 demo-home/,不碰真正的数据目录。

日常用

菜单栏只有一个开关:开启或关闭录音、打开时间线、退出。图标是波形表示在录,喇叭表示电脑在放声音、暂停中,斜杠麦克风表示已关闭。

命令行(.venv/bin/tingji):

命令

做什么

status

录音和后台在不在跑、整理到几点、今天记了什么

events --day 2026-10-26

某天的全部事件

pieces

最近录下的段,注册声纹时用来找编号

enroll --piece N / enroll --file 录音

给「我」加一个声纹样本

relabel

加了样本以后,把已有的句子重新认一遍

flush

不等 5 分钟,马上把已经转写的话整理成事件

redo --day D

删掉某天的事件重新整理(改了提示词以后用)

import-memos --dry-run

看看有多少条 iPhone 语音备忘录可以导入;去掉 --dry-run 才真导

digest --day D

马上写某天的总结

insights

马上做一次觉察

设置:在 ~/Library/Application Support/Tingji/settings.json 里写要改的项,后台每一轮都会重新读。

设置

默认

说明

owner

"用户"

你的名字,写进给模型的提示词

keep_audio_days

30

有人声的录音留多少天,0 表示一直留。文字永远保留

event_gap_s

300

两段话隔开多少秒以上算两件事

voice_match

0.6

声纹相似度到多少算「我」

llm_model / llm_fast_model

deepseek-v4-pro / deepseek-v4-flash

整理用的模型;一件事里说话不到 8 秒的用快的那个

mic_device_uid

空

指定用哪个麦克风,默认跟系统的默认输入走。设备 UID 用 /Applications/听记.app/Contents/MacOS/Tingji --probe 查

web_port

7788

时间线网页的端口

「今天」按北京时间算,要改时区就改 tingji/config.py 里的 TZ。

数据放在哪

全部在 ~/Library/Application Support/Tingji/:

  • tingji.db:SQLite,里面是逐句原文、事件、项目、总结、觉察和声纹

  • audio/:有人声的录音,按天分目录,每小时人声约 14 MB

  • settings.json、secrets.json(API key,权限 600)

日志在 ~/Library/Logs/Tingji*.log。

会离开这台电脑的只有两样:有人声的录音片段,上传到阿里云百炼的临时存储做转写(百炼 48 小时后自动删除);转写出来的文字,发给 DeepSeek 整理。人声检测和声纹都在本机算,时间线网页只对本机开放。

怎么做的

flowchart LR
  A["菜单栏录音开关<br/>16 kHz 单声道,一分钟一片"] --> B["人声检测<br/>Silero VAD,本机"]
  B -->|没人说话| X["删掉"]
  B -->|有人说话| C["拼成段<br/>Fun-ASR 转写,分说话人"]
  C --> D["认出「我」<br/>CAM++ 声纹,本机"]
  D --> E["按话题切成事件<br/>DeepSeek"]
  E --> F["项目、日总结、觉察<br/>DeepSeek"]
  E --> G[("SQLite")]
  F --> G
  G --> H["时间线网页"]
  G --> I["MCP,给 Agent 读"]

位置

是什么

app/

菜单栏录音开关(Swift):录麦克风、电脑出声时暂停、每分钟交一片

tingji/worker.py、pipeline.py

后台,每 3 秒跑一轮:人声检测、拼段、转写、认声纹、切事件、归项目、总结、觉察

tingji/asr.py、llm.py、prompts.py

Fun-ASR、DeepSeek 和给 DeepSeek 的提示词

tingji/audio.py、voice.py

解码和人声检测、声纹

tingji/web.py、web/index.html

时间线网页

tingji/mcp_server.py

MCP;网页的接口直接复用这里的函数,网页和 Agent 看到的是同一份

tingji/cli.py

命令行

录音开关用 Swift 写,是因为 macOS 的麦克风权限是按 .app 给的,要一个签了名、写明用途的 .app 才能弹出授权。其余都是 Python。

费用

Fun-ASR 每小时 ¥0.79,只算有人声的部分。DeepSeek 每件事调一次,每个项目更新一次,每天一次总结,每周一次觉察。

我自己第一天从下午一点多开到半夜:录到 2 小时人声,1100 多句,4 万多字,转写花了不到 2 块钱。

还没做

  • 通话对方的声音:现在只录麦克风,戴耳机打电话时只录得到自己这边。

  • 多台电脑汇总到一台服务器,给团队一起用。

  • 随口记和标重点:后台已经能处理,菜单栏还没加快捷键。想自己接的话,往数据目录的 marks.jsonl 里追加一行 {"ts": 毫秒时间戳, "kind": "highlight"},或者一对 note_start / note_end。

卸载

./uninstall.sh

会停掉三个后台服务、删掉 /Applications/听记.app。录音和文字都还留在数据目录里,不要了再自己删。

致谢

License

MIT。作者边淬火,X:@Biancuihuo

Available Tools

11 tools
day_summaryB

某一天的总结:一句话概括、上午/下午/晚上各干了什么、待办、承诺、风险。当天的在 23:30 以后自动生成。

NameRequiredDescriptionDefault
dayNoyesterday

Output Schema

NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the safety/behavior burden: it discloses the return structure and the 23:30 generation timing, which is genuinely useful behavioral context. It does not say whether the tool reads or generates, what happens for a not-yet-generated day, or any access constraints, so gaps remain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences, front-loaded with the purpose and contents before the timing caveat; there is no filler. Slightly dense but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description needn't document return values, and it correctly focuses on content scope and the 23:30 timing. Still, it omits the `day` parameter's semantics and the behavior when a summary is unavailable, leaving meaningful holes for a one-param retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must explain the single `day` parameter — its accepted format, valid values, and how the default 'yesterday' behaves. The description never mentions the parameter at all, so an agent must guess the date format from the schema's bare string type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource (a single day's summary) and enumerates its concrete contents (one-line overview, morning/afternoon/evening activities, todos, commitments, risks), which makes the tool's output distinguishable from siblings like `insights` or `todos`. The retrieval verb is only implied, and no sibling is named as an alternative, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides one useful temporal constraint — today's summary is auto-generated only after 23:30 — which tells the agent when the tool is meaningful. However, it never states when to prefer this over siblings such as `insights` or `search`, nor what to expect if the summary does not yet exist, leaving usage largely inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_projectC

一个项目的档案:现状、阶段、风险、下次该追问的问题、谁答应过什么,以及时间线上的每件事。

NameRequiredDescriptionDefault
project_idYes

Output Schema

NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden, yet it only lists content categories. It does not state that this is a read-only lookup, what happens with an unknown or inaccessible project_id, permission requirements, or result size/pagination — leaving the agent uninformed about behavior beyond the payload shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single front-loaded sentence with no filler; the enumerated content list earns its place by telling the agent what the payload covers. The only weakness is a slightly sprawling list of six items that blurs the primary purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be spelled out, and the description does convey the breadth of the payload. But for a tool requiring an undocumented identifier with zero annotations, the absence of any input or usage information leaves a meaningful gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single required parameter project_id is documented nowhere. The description never mentions that a project identifier is required or what form it takes, so it fails to compensate for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description characterizes the resource as a project's dossier and enumerates its contents (status, phase, risks, open questions, commitments, timeline), which makes the subject clear. However, it never states the action (retrieve a single project by ID) and offers no differentiation from siblings like get_record or list_projects, so an agent must infer that this is the per-project fetch tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus get_record, list_projects, insights, or day_summary. The description implies 'use this to see a project's full picture' but never states a selecting condition or any exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_recordB

按 ID 取一条记录的全部字段。E 开头是全时记(摘要、要点、待办、决定、重点、人、记忆,可带逐句原文);N 开头是随口记;P 开头是项目。

NameRequiredDescriptionDefault
record_idYes
include_transcriptNo

Output Schema

NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full behavioral burden. It conveys that this is a read operation that returns the record's full field set, and it lists the content types that may come back (including optional sentence-level transcripts), but it says nothing about the authorization needed to access a record, what happens when the ID is not found, or how the transcript payload is shaped.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two compact clauses that front-load the core action and then add ID semantics. There is no filler, though the taxonomy takes up most of the space while a more important parameter goes unmentioned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description need not unpack return values, and the ID-prefix explanation covers the main input. The missing piece is include_transcript and the relationship to get_transcript or get_project, which an agent would need in order to choose correctly among the siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema coverage is 0%, so the description has to compensate. It does add meaningful semantics for record_id through the E/N/P prefix taxonomy, which the schema does not. However, it says nothing about include_transcript, the second parameter, even though that parameter defaults to true and overlaps with the get_transcript sibling.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: fetch all fields of one record by ID, and it adds a prefix taxonomy (E/N/P) that tells the agent what kind of object each ID designates. It does not, however, separate this tool from get_transcript or get_project, even though their names suggest overlap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives, despite sibling tools named get_transcript, list_records, and get_project. The prefix explanation implies the usage scope, but it leaves the agent to infer whether this is the right tool when the goal is a transcript or a project.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_transcriptA

逐句原文(语音转写的原话,带时间和说话人),不管有没有整理成事件。 start/end 同 list_records;source:all / mic(现场)/ system(通话对方)/ memo(导入的备忘录);speaker:只看某人,如「我」「对方」。最多返回 1500 句。

NameRequiredDescriptionDefault
endNo
startYes
sourceNoall
speakerNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does disclose useful traits: raw (unprocessed) speech data, per-sentence time and speaker metadata, and a hard cap of 1500 sentences. It does not say what happens past 1500 (truncation vs. pagination) or how to page, which is the main behavioral gap for a bulk-retrieval tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense and front-loaded: what the tool returns comes first, then parameter semantics, then the result cap. Every clause carries information, though the '同 list_records' cross-reference is less self-contained than an inline format note would be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter read tool with an output schema present (so return structure needn't be restated) and no annotations, the description covers purpose, all parameters, and the result cap. The remaining gaps — start/end format and overflow behavior — are real but narrow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it largely does: all four parameters are explained, with source enumerating all/mic/system/memo and what each means, and speaker given worked examples ('我', '对方'). The weakness is start/end, which are only defined by cross-reference to list_records rather than a format example.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete resource and scope: sentence-by-sentence verbatim transcript with time and speaker, explicitly 'regardless of whether it was organized into events'. That last clause implicitly separates it from the record-oriented siblings (list_records/get_record), though it never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied — the contrast with '整理成事件' suggests when raw transcript is wanted over records, but no sentence says 'use this when ... instead of get_record/list_records'. The per-filter meanings of source and speaker give operational context but not selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

insightsB

觉察:每周从「我」说过的话里找出的沟通和做事习惯,每条带依据和建议。

NameRequiredDescriptionDefault
limitNo

Output Schema

NameRequiredDescription
resultYes

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It usefully discloses the data source (things the user said) and the output shape (each item ships with evidence and a suggestion), but says nothing about read-only semantics, freshness, or how the limit affects results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the concept and then the derivation and item structure. No wasted text; the only small cost is the terse Chinese label '觉察' which is less self-explanatory than the rest.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complexity is low and an output schema exists, so return-value explanation is not required. Still, for a tool an agent must choose against memories/day_summary, the missing usage routing and undocumented limit leave it only minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single parameter 'limit' (default 10) is never mentioned in the description. While the parameter is fairly self-evident from its name and default, the description does nothing to compensate for the total coverage gap or clarify what is being limited.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource: weekly-derived communication and work habits extracted from the user's own speech, each with evidence and suggestions. That is far more concrete than the bare name 'insights'. It does not, however, distinguish this from siblings like memories or day_summary, which also surface derived personal context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit statement of when to call this versus alternatives such as memories or day_summary, and no prerequisites or exclusions. The 'weekly' cadence hints at scope but an agent must infer the trigger condition (user asking about their own habits).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_projectsA

跨天自动归集的项目(同一件事在不同时间的几次谈话串成一条线),按最近更新排序。

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the disclosure burden. It adds useful behavioral context by stating that projects are auto-aggregated across days and returned in most-recent-update order, but it does not explicitly say this is a read-only listing, whether it returns all projects, or what scope limitations exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is a single compact sentence with no filler. It front-loads the nature of the projects and then states the sort order, so every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter list tool with an output schema, the description covers the key semantics: what a project is, how projects are formed, and how results are ordered. It is slightly incomplete on usage context and read-only/scope behavior, but the output schema reduces the need to describe return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters and schema description coverage is 100%, so there are no parameter semantics to explain. The baseline for a zero-parameter tool is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The name supplies the verb 'list' and the description defines the resource as cross-day auto-aggregated projects, including that related conversations are linked into one thread. It does not explicitly contrast with siblings such as get_project or list_records, so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what projects are and that they are sorted by most recent update, but gives no explicit instruction on when to use this tool versus list_records, get_project, or other siblings. Usage is only inferable from the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_recordsA

列出一段时间里的全时记(自动切出来的一件件事)和随口记(按快捷键说的灵感/提问/待办)。 start/end:'2026-10-25'、'2026-10-25 14:00'、'today'、'yesterday';end 留空 = start 那天结束。 kind:all / events / notes。min_importance:1 全部,2 去掉零碎小事,3 只看重要的。

NameRequiredDescriptionDefault
endNo
kindNoall
startNotoday
min_importanceNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does disclose what is returned (two record types) and the empty-end semantics. It omits ordering, result-size limits, pagination, and whether results span all projects — meaningful gaps for an unannotated listing tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded: the what-it-lists sentence comes first, then terse per-parameter notes with no filler. The telegraphic 'start/end:… kind:…' style is efficient, though slightly dense for readers unfamiliar with the domain vocabulary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape is covered, and all four parameters are explained. What remains missing for an unannotated, four-parameter listing tool is behavioral context: ordering, pagination or caps, and confirmation that it is a pure read.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description has to compensate and largely does: it gives accepted date/time formats ('2026-10-25', '2026-10-25 14:00', 'today', 'yesterday'), the meaning of an empty end, the kind enum (all/events/notes), and a graded scale for min_importance. The only miss is the start='today' default behavior and any timezone caveat.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and two concrete resources ('全时记' auto-segmented events and '随口记' quick notes/ideas/questions/todos), scoped to a time range. An agent can tell what comes back. It stops short of naming a sibling it is *not* (search, day_summary, get_record), so the differentiation is incomplete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the filter semantics: narrowing by kind and raising min_importance to drop trivia suggests this is the browse/scan-the-timeline tool. But the description never says when to prefer it over search, day_summary, or get_record, and gives no exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memoriesA

长期记忆:从各件事里抽出来值得长期记住的事实(人、偏好、约定、数字等),带出处。query 留空返回最近的。

NameRequiredDescriptionDefault
limitNo
queryNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations to lean on, but the description does disclose meaningful behavior: results are facts (people, preferences, agreements, numbers) that carry sources ('带出处'), and the default empty-query behavior is stated. It does not state that the tool is read-only or clarify what happens to the results (ordering, truncation).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, front-loaded clauses with zero waste; the resource definition comes first and the mode-specific behavior second.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema, so return shape need not be described, and the description still tells the agent what kinds of objects come back and that they carry sources. The only real gap is the unexplained `limit` and the lack of sibling routing guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It fully explains `query` semantics ('empty returns most recent'), but `limit` is not mentioned in the description at all (only its default 50 in the schema). Half-documented parameters warrant a middling score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The definition names a specific resource – long-term facts extracted from events, with provenance – which is distinct from sibling tools like `search` (raw search) and `insights` (aggregated patterns). The retrieval verb is only implicit (it doesn't say 'return/list'), but 'query 留空返回最近的' makes it clear this is a retrieval tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains one mode explicitly: empty query → return most recent. However, it never routes the agent to or away from alternatives such as `search`, `insights` or `list_records`, so selecting this tool over a sibling is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recorder_statusB

录音器现在在不在录、录哪个麦克风、哪些通话软件、整理到几点了。

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are supplied, so the description carries the disclosure burden. It implies a read-only status query by describing what is reported (recording state, microphone, call apps, processing progress), but never explicitly states it has no side effects or how current the status snapshot is. For a zero-parameter status tool the risk is low, so this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact clause that front-loads the core question (is it recording) before the secondary facets. No filler, though it reads as a sentence fragment without an explicit action verb.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters and an output schema that carries the return-value detail, the description only needs to frame what the status covers, which it does. Nothing essential for invoking the tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; schema coverage is 100% and empty.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the specific resource (the recorder) and enumerates what status facets are reported: whether it is recording, which microphone, which call apps, and how far processing has progressed. This clearly distinguishes it from siblings like list_records or get_record. The only weakness is that the verb is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance and no mention of alternatives. An agent can infer from the name and content that this is a status check, but nothing tells it when this is preferable to, say, list_records for checking recording output.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

todosB

最近几天全时记里冒出来的待办和承诺(谁、做什么、什么时候),以及随口记里的待办。

NameRequiredDescriptionDefault
daysNo

Output Schema

NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden, and it does disclose that results are aggregated from two separate note sources and include commitment metadata. It says nothing about ordering, deduplication, limits, or whether the operation is read-only, leaving meaningful behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence with the resource and the recency scope front-loaded and no filler. It is efficient, if slightly under-specified rather than padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. For a simple aggregation read this is borderline adequate, but the undocumented `days` semantics and the absence of any safety or ordering context leave it short of complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% for the single `days` parameter, so the description must compensate. "最近几天" loosely signals that a recency window exists, but it never ties that to the `days` parameter, its default of 7, or what the boundary means.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete resource (todos and commitments) and two specific sources (全时记 and 随口记), plus the attributes captured (who, what, when). It is clearly distinguishable from generic record tools, though it does not explicitly name a sibling to contrast with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies a recency window ("最近几天"), but offers no guidance on when to pick this over day_summary, list_records, or memories, nor any exclusions or prerequisites. An agent must infer the routing decision entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 11 tool updatesv0.1.0
    • First observedday_summary
    • First observedget_project
    • First observedget_record
    • First observedget_transcript
    • First observedinsights
    • First observedlist_projects
    • First observedlist_records
    • First observedmemories
    • First observedrecorder_status
    • First observedsearch
    • First observedtodos

TDQS

B3.3/5.0

Scored across 11 tools

Disambiguation4/5

Most tools target distinct resources: raw transcript (get_transcript), records/events (list_records, get_record), projects (list_projects, get_project), and derived artifacts (todos, day_summary, insights, memories, recorder_status). There is minor overlap: get_record also accepts P (project) IDs while get_project exists, and todos overlaps with both list_records(kind=notes) and day_summary, which also surfaces todos and commitments. Descriptions mostly resolve these, but an agent could plausibly pick the wrong one for 'what did I promise'.

Naming Consistency3/5

Half the set follows a clean verb_noun pattern (list_records, get_record, get_transcript, list_projects, get_project), but the rest are bare nouns or verbs (search, todos, day_summary, insights, memories, recorder_status). Each name is still readable and self-explanatory, so this is mixed convention rather than chaos.

Tool Count5/5

11 tools is well within the healthy range and each maps to a distinct query surface of a personal recording/memory app: time-ranged listing, single-record fetch, transcript, keyword search, todos, projects, daily summary, weekly insights, long-term memories, and recorder status. Nothing feels padded or redundant enough to drop.

Completeness4/5

The read/retrieval lifecycle is well covered: discover (list_records, search, list_projects), drill down (get_record, get_transcript, get_project), and synthesize (todos, day_summary, insights, memories), plus operational status. Gaps are minor and likely intentional: no write/mutation operations (edit a todo, correct a memory), and no way to jump from an insight or memory entry back to its source event in one call.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    C
    maintenance
    Local-first ambient memory for Mac that captures screen content, indexes it on-device, and provides MCP tools for searching memory, timeline, and open tasks.
    MIT
  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI assistants to search and retrieve memories from your Mac, including screen captures, meeting transcripts, and browsing history, all locally and privately.
    1
    Elastic 2.0
  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to query your complete local conversation history and knowledge graph over MCP, including full-fidelity transcripts, search, and typed, dated entity relationships.
    AGPL 3.0
  • A
    license
    Not graded
    quality
    B
    maintenance
    Provides a local AI assistant with tools to query your computer's episodic memory, such as where you were, what you were working on, activity summaries, and timeline details, all sourced from a privacy-filtered SQLite database.
    MIT