Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@ All notable changes to this project will be documented in this file.

## [Unreleased]

### Changed
- Removed the timestamp from the shared startup map. Reuse host-provided date/time context and verify precise time on demand; per-turn time injection remains a future option, not an enabled hook.

### Added
- **Tasks can point at scraps** — a task record carries an optional `scraps` list of scrap ids (same shape as `people`). Set it from the task detail (a searchable picker), from a scrap's detail ("+ 关联或新建一个任务" — type a title that does not exist yet and it creates the task already linked), or with `loci-task.js add/update --scraps "ref:a,ref:b"`; chips on the task card open the scrap, and the scrap lists its tasks. Stored one way, on the task; a scrap that is later archived shows as a dashed chip. A scrap is never turned into a task — the task points at it.

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Loci 的核心是让不同 Agent 通过自己的原生指令入口,使用同

## 一次对话怎样运行

1. **会话启动**:客户端加载短入口。有有效 Hook 输出则使用它;没有则让 Agent 执行同一个 `loci-context.js`。启动输出只有时间、路径、短偏好和手册指针,不再携带任务路由表、状态摘要或项目正文。
1. **会话启动**:客户端加载短入口。有有效 Hook 输出则使用它;没有则让 Agent 执行同一个 `loci-context.js`。启动输出只有路径、短偏好和手册指针,不再携带时间、任务路由表、状态摘要或项目正文。日期与时间优先复用宿主已有信息,需要更高精度时按需核对。
2. **普通问题**:如果不涉及记忆读取,也没有值得保存的明确内容,无需读完整手册。
3. **首次需要 Loci**:例如“明天9点发材料”,或正常讨论中形成一个明确任务,Agent 先完整读取 `LOCI-RULES.md`,然后按规则调用任务工具。不能只在用户说“记住”时才触发。
4. **后续使用**:手册已在上下文中就复用。只读当前所需数据,写入后按实际结果确认。手册被截断需补齐;压缩后丢失、版本变化需重读。
Expand Down
2 changes: 1 addition & 1 deletion docs/context-awareness.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 上下文与跨终端变更

启动只提供短偏好、时间和路径。任务、计划、状态与项目正文按需读;最新信息刷新最小相关来源。
启动只提供短偏好、路径和手册指针。日期与时间优先复用 Agent 已提供的信息,Loci 不重复注入;精确时间不足或信息过期时按需核对。任务、计划、状态与项目正文按需读;最新信息刷新最小相关来源。

`check-updates.js` 可读取已有跨终端变更日志,`on-file-change.js` 记录其支持的文件写入。它们不代表所有客户端都有自动监听,也不在每次启动全量整理。

Expand Down
8 changes: 5 additions & 3 deletions docs/context-explained.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
| 内容 | 它回答什么问题 | 内容来自哪里 | 何时读到 |
| --- | --- | --- | --- |
| `LOCI.md` 短入口 | 大脑在哪里?先做什么?何时查手册? | 产品维护的短规则,安装时替换路径后写入宿主入口 | 宿主加载原生指令时 |
| 启动地图 | 此刻路径、时间、用户短偏好是什么? | `loci-context.js` 读取实际偏好,结合运行时路径生成 | 有效 Hook 注入,或 Agent 按入口调用同一脚本 |
| 启动地图 | 大脑在哪、用户短偏好是什么、去哪里读规则? | `loci-context.js` 读取实际偏好,结合运行时路径生成 | 有效 Hook 注入,或 Agent 按入口调用同一脚本 |
| `LOCI-RULES.md` 完整手册 | 这类内容应该怎么读、怎么保存、怎么确认? | 产品维护的一份业务规则文件 | 首次涉及 Loci 操作时完整读取;有效且未变时复用 |

## LOCI.md:入口到底写了什么
Expand Down Expand Up @@ -42,10 +42,12 @@

## 启动地图:实际会注入哪段文字

日期与时间优先复用 Agent 已提供的信息,Loci 不重复注入。启动地图只提供短偏好、位置和规则指针;涉及精确时间时按需核对。逐轮时间补充留作[后续可探索项](https://www.tryloci.com/handbook/#待探索宿主时间不足时再补充),当前未启用。

以下由当前 `loci-context.js` 在临时目录中真实运行生成,偏好为虚构示例,输出路径替换为 `/example/loci` 与 `/example/work`。没有读取任何人的真实资料;不要把示例路径用于实际连接。

```text
[Loci] Lightweight startup map · 2026-10-08 09:00 Thu
[Loci] Lightweight startup map
Brain: /example/loci
Workspace: /example/work
This startup map is already loaded. Do not run it again in this session.
Expand All @@ -65,7 +67,7 @@ Do not preload plans, tasks, inbox, journals, project memory, or history. Read t

| 输出字段 | 意思与目的 |
| --- | --- |
| `[Loci] Lightweight startup map` 与时间 | 标识这是读取器的启动输出;时间是生成时的本地时间,不会在对话过程中自行刷新 |
| `[Loci] Lightweight startup map` | 标识这是读取器的启动输出;不包含日期或时间 |
| `Brain` | 本次连接的大脑位置,后续从这里定位规则和数据 |
| `Workspace` | 当前工作目录,提供运行环境位置;不代表项目正文已读入,也不代表这个目录自动成为大脑 |
| `already loaded` | 提醒 Agent 本会话不要又跑一遍读取器,避免 Hook 和后备调用重复 |
Expand Down
44 changes: 24 additions & 20 deletions docs/user-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,12 +103,12 @@ Loci 不会修改模型权重,也没有给模型增加一种生物式记忆。

这里解释当前架构中模型会看到的三类内容。**需要维护的是两份规则文件;启动地图是程序现场生成的一段文本,不是第三份规则文件。** 用户的偏好和实际记录则保存在大脑数据中。

> **入口 → 会话信息 → 操作手册。** `LOCI.md` 告诉 Agent:有 Loci,大脑在哪、先获取什么、何时查手册。启动地图提供这次会话应先知道的短偏好、生成时间和位置。`LOCI-RULES.md` 说明具体信息怎样读取、保存和更新。实际任务、人物和笔记另存在数据文件里,相关时再读。
> **入口 → 会话信息 → 操作手册。** `LOCI.md` 告诉 Agent:有 Loci,大脑在哪、先获取什么、何时查手册。启动地图提供这次会话应先知道的短偏好和位置。`LOCI-RULES.md` 说明具体信息怎样读取、保存和更新。实际任务、人物和笔记另存在数据文件里,相关时再读。

| 内容 | 它回答什么问题 | 内容来自哪里 | 何时读到 |
| --- | --- | --- | --- |
| `LOCI.md` 短入口 | 大脑在哪里?先做什么?何时查手册? | 产品维护的短规则,安装时替换路径后写入宿主入口 | 宿主加载原生指令时 |
| 启动地图 | 此刻路径、时间、用户短偏好是什么? | `loci-context.js` 读取实际偏好,结合运行时路径生成 | 有效 Hook 注入,或 Agent 按入口调用同一脚本 |
| 启动地图 | 大脑在哪、用户短偏好是什么、去哪里读规则? | `loci-context.js` 读取实际偏好,结合运行时路径生成 | 有效 Hook 注入,或 Agent 按入口调用同一脚本 |
| `LOCI-RULES.md` 完整手册 | 这类内容应该怎么读、怎么保存、怎么确认? | 产品维护的一份业务规则文件 | 首次涉及 Loci 操作时完整读取;有效且未变时复用 |

### LOCI.md:入口到底写了什么
Expand Down Expand Up @@ -145,11 +145,13 @@ Loci 不会修改模型权重,也没有给模型增加一种生物式记忆。

#### 作用:让 Agent 开始时就知道少量重要信息

启动地图给 Agent 一份**本次会话的简短说明**:用户希望怎样协作、现在生成这段信息的时间、大脑和操作手册在哪里。这样,第一句回复就能照顾用户的语言、称呼和工作习惯,后续也有查找记忆的入口。
启动地图给 Agent 一份**本次会话的简短说明**:用户希望怎样协作、大脑和操作手册在哪里。这样,第一句回复就能照顾用户的语言、称呼和工作习惯,后续也有查找记忆的入口。

它不只有偏好。**当前代码已经输出:短偏好、生成时的本地日期与时间、大脑路径、当前工作目录、入口与手册指针,以及避免重复加载的提示。** 用户习惯只要已写入 `me/preferences.md` 的短偏好范围,就能一并带入;读取器不会自己分析聊天、推测用户性格或总结全部历史。
它不只有偏好。**当前代码输出:短偏好、大脑路径、当前工作目录、入口与手册指针,以及避免重复加载的提示。** 用户习惯只要已写入 `me/preferences.md` 的短偏好范围,就能一并带入;读取器不会自己分析聊天、推测用户性格或总结全部历史。

这里的“动态”指**运行读取器时,从当前文件和运行环境现场取值**。注入后,它就是上下文中的一份快照。上午9点生成的时间,到下午仍写着9点;偏好文件后来被另一位 Agent 修改,旧会话中的文本也不会自动变化。涉及“现在、今天、最新”的问题,要重新获取当前时间或读取最小的相关来源,不能把启动快照当成实时状态。
这里的“动态”指**运行读取器时,从当前文件和运行环境现场取值**。注入后,它就是上下文中的一份快照。例如,偏好文件后来被另一位 Agent 修改,旧会话中的文本不会自动变化;需要最新信息时,刷新最小的相关来源。

> **时间由宿主提供,Loci 不重复注入。** 复用 Agent 已有的日期或时间上下文,当前启动地图不再附带时间戳,也不增加每轮时间 Hook。不同宿主提供的精度和时区可能不同;涉及精确时间的操作,仍需按需核对。额外时间补充只列入[后续可探索项](#待探索宿主时间不足时再补充)。

#### 可以再加入什么,哪些还没有实现

Expand All @@ -158,7 +160,7 @@ Loci 不会修改模型权重,也没有给模型增加一种生物式记忆。
| 信息 | 例子 | 当前状态与放置方式 |
| --- | --- | --- |
| 沟通偏好与稳定工作习惯 | 中文短答、先给结论、专注工作时少打断 | 已支持从 `me/preferences.md` 读取;只在短偏好预算内输出 |
| 时间与运行位置 | 生成时的日期、时间,大脑与工作目录 | 已输出;时间来自运行读取器的环境,当前没有单独的时区字段 |
| 运行位置与规则入口 | 大脑与工作目录、短入口与完整手册路径 | 已输出,便于 Agent 找到实际数据与规则 |
| 当前协作中需要关注的状态 | “今天只安排线上活动”“本周先完成一个项目” | 可扩展,当前不会自动读取;若加入,应从有来源、更新时间和有效期的短状态记录获取 |
| 用户明确希望被提醒的行为约定 | “规划时保留连续的专注时间” | 长期且常用的可写入偏好;临时约定应带期限,不把模型猜测固化为用户习惯 |
| 具体任务、日程、人物与历史 | 今天全部待办、所有会议、某人的完整往来 | 当前按需读取;需要安排今天时再查任务与日程,无需每个会话都带入 |
Expand All @@ -170,7 +172,7 @@ Loci 不会修改模型权重,也没有给模型增加一种生物式记忆。
以下由当前 `loci-context.js` 在临时目录中真实运行生成,偏好为虚构示例,输出路径替换为 `/example/loci` 与 `/example/work`。没有读取任何人的真实资料;不要把示例路径用于实际连接。

```text
[Loci] Lightweight startup map · 2026-10-08 09:00 Thu
[Loci] Lightweight startup map
Brain: /example/loci
Workspace: /example/work
This startup map is already loaded. Do not run it again in this session.
Expand All @@ -190,7 +192,7 @@ Do not preload plans, tasks, inbox, journals, project memory, or history. Read t

| 输出字段 | 意思与目的 |
| --- | --- |
| `[Loci] Lightweight startup map` 与时间 | 标识这是读取器的启动输出;时间是生成时的本地时间,不会在对话过程中自行刷新 |
| `[Loci] Lightweight startup map` | 标识这是读取器的启动输出;不包含日期或时间 |
| `Brain` | 本次连接的大脑位置,后续从这里定位规则和数据 |
| `Workspace` | 当前工作目录,提供运行环境位置;不代表项目正文已读入,也不代表这个目录自动成为大脑 |
| `already loaded` | 提醒 Agent 本会话不要又跑一遍读取器,避免 Hook 和后备调用重复 |
Expand Down Expand Up @@ -258,7 +260,7 @@ Do not preload plans, tasks, inbox, journals, project memory, or history. Read t
| 内容 | 由谁提供 | 时机 | 是否每条消息重复 |
| --- | --- | --- | --- |
| 短入口规则 | 宿主读取原生指令文件 | 会话建立及宿主定义的加载时机 | 由宿主管理,不让 Agent 每条消息重复读取 |
| 时间、短偏好、大脑和手册指针 | Hook 或 Agent 调用同一读取器 | 会话启动;已有有效输出则复用 | 不重复启动读取 |
| 短偏好、大脑和手册指针 | Hook 或 Agent 调用同一读取器 | 会话启动;已有有效输出则复用 | 不重复启动读取 |
| 完整操作手册 | Agent 文件读取工具 | 首次涉及 Loci 读写,或发现明确可保存信号时 | 已完整读取且有效时复用 |
| 任务、人脉、笔记、项目等实际数据 | Agent 文件或命令工具 | 当前问题需要时 | 只刷新最小相关来源 |
| 工具执行结果 | 脚本/API 返回 | 每次实际操作之后 | 本次结果用于本次确认 |
Expand All @@ -274,28 +276,21 @@ Hook 是一个宿主事件触发的程序入口。它能让偏好在启动时更

### 启动 Hook,还是每轮 Hook

**Loci 当前采用启动注入,加上相关时按需刷新。** 稳定偏好适合在会话开始时提供,当前时间与易变数据则在实际需要时重新取值。这样能兼顾第一句回复的个性化和后续信息的新鲜度。
**Loci 当前采用启动注入,加上相关时按需刷新。** 稳定偏好适合在会话开始时提供,易变数据在实际需要时重新读取。日期与时间优先复用宿主已有信息,不另做重复注入。

先区分触发时机。以 Claude Code 为例,`SessionStart` 在会话开始、恢复等生命周期事件触发;`UserPromptSubmit` 在一轮输入交给模型处理前触发;`Stop` 在模型完成回复时触发。若想让补充信息影响本轮回答,应在处理输入前提供。一次输入可能带来多次工具调用和模型生成,不能把“每轮输入前”理解成“每生成一句话前”。具体事件由宿主及版本决定。[Claude Code Hook 文档](https://code.claude.com/docs/en/hooks#hook-lifecycle)

| 方式 | 适合提供什么 | 代价与边界 |
| --- | --- | --- |
| 启动 Hook | 短偏好、大脑位置、规则指针、启动时刻 | 调用频率低;会话很长或外部文件有变更时,快照可能过期 |
| 每轮输入前 Hook | 更新后的时间、已变更的偏好、已过期状态的更正 | 可以更及时,但每轮有执行成本;整份重复注入会增加上下文负担,运行慢也会延迟回答 |
| 启动 Hook(当前采用) | 短偏好、大脑位置、规则指针 | 调用频率低;会话很长或外部文件有变更时,快照可能过期 |
| 每轮输入前 Hook(未启用) | 已变更的偏好、已过期状态的更正等少量变化 | 可以更及时,但每轮有执行成本;整份重复注入会增加上下文负担,运行慢也会延迟回答 |
| Agent 按需读取 | 排日程时取当前时间,问今天时查当天数据,提到某人时读对应档案 | 读取范围小;依赖 Agent 识别触发条件并正确执行 |

启动注入的内容只要还在有效上下文中,后续轮次就可以继续使用,并非只影响第一条回复。上下文被压缩或重置后,仍需要恢复关键内容。

当前仓库的 Claude 接入配置了 `startup|resume|clear|compact|fork`,Codex 接入配置了 `startup|clear|compact`;这些是安装器写入的匹配条件,实际触发以宿主支持为准。因此,“启动 Hook”也可能在清空或压缩后再次提供地图。**当前 Loci 没有安装用于逐轮注入地图的 `UserPromptSubmit` Hook。** 写文件后的活动记录 Hook 另有用途,不等于逐轮更新上下文。

如果以后确实需要更强的实时感,建议在现有启动方案上增加一个很轻的每轮检查,而不是每轮重新载入整份地图或完整手册:

1. **只补变化。** 偏好未变就不重复输出;发生变更时,提供新的短值并注明替代旧值。临时状态到期时也要明确失效,不能只停止输出、让旧状态继续留在上下文里。
2. **时间单独处理。** 对时间敏感的请求获取当前时间和明确时区;若产品选择每轮提供时间,只加一行即可。宿主已经提供可靠时间时避免重复。
3. **保持轻量。** 做文件变更或有效期检查,不在每轮扫描全部历史、调用模型总结用户、或远程检索。对读取耗时和输出长度设上限,失败不阻塞普通聊天。
4. **所有 Agent 共用来源。** 有相应 Hook 的宿主自动补充;其他宿主保留入口指引和按需读取。不要为每个 Agent 维护一份不同的用户状态。

以上是后续扩展建议,本次说明没有启用逐轮 Hook。当前选择是:**入口保持短,启动先带上必要信息,首次操作读规则,易变数据用到再刷新。**
如果以后增加逐轮补充,应只发送实际变化,注明旧状态失效,设置耗时与输出上限,并让所有 Agent 共用数据来源。当前保持:**入口保持短,启动先带上必要信息,首次操作读规则,易变数据用到再刷新。**

源码依据:[启动读取器](https://github.com/codesstar/loci/blob/main/scripts/loci-context.js)、[Claude Hook 配置](https://github.com/codesstar/loci/blob/main/scripts/loci-claude-settings.js)、[Codex Hook 配置](https://github.com/codesstar/loci/blob/main/scripts/loci-codex-hook.js)。宿主事件语义参考 [SessionStart](https://code.claude.com/docs/en/hooks#sessionstart) 与 [UserPromptSubmit](https://code.claude.com/docs/en/hooks#userpromptsubmit)。

Expand Down Expand Up @@ -785,6 +780,15 @@ Issue #7 报告 Windows 盘符开头的外部笔记路径被静默跳过。报
| 中 | 提醒可观测性 | 保存和送达之间缺少直观状态 | 可区分已保存、调度、发送失败、设备验收 |
| 中 | 笔记读写边界与大库检索 | 读界面、旧编辑 API、挂载上限存在历史包袱 | 明确权限与路径策略,达到上限有提示,索引可刷新 |
| 待探索 | 跨设备同步 | 有真实需求,但文件冲突不是复制目录就能解决 | 先定义单写者/冲突副本/恢复,再验证双设备离线修改 |
| 待探索 | 宿主时间不足时的轻量补充 | 优先复用 Agent 已有时间能力,仅在实际出现不足时考虑 | 明确日期、时刻、星期与时区;避免重复;跨时区与长会话验证 |

### 待探索:宿主时间不足时再补充

**当前不做独立时间注入。** Agent 已有的日期或时间上下文由宿主负责,Loci 优先复用;精确时间不足、过期或时区不明确时,通过工具按需核对。

如果后续在实际使用中发现宿主时间支持不足,再考虑在支持的客户端通过 `UserPromptSubmit` 只补几行时间信息。输出应明确写出日期、时刻、星期和时区,并说明它是本轮输入处理前获取的时间;不把时间藏在启动地图标题里,也不每轮重发偏好和完整规则。长任务执行过程中需要精确计时时,仍要重新获取时间。

这是后续可做的方向,尚未启用,也没有排定实施时间。

### 为什么优先改善这些问题

Expand Down
Loading
Loading