Personal MCP Core

橙色花园

*一个用于事件、注释和人工智能解释的个人可观察性花园。*

橙色花园 是一个软件盆景。

这是一个长期存在的个人可观察性系统， 注释和解释随着时间的推移逐渐增长。

橙色花园没有把软件当作需要完成的事情 将其视为需要培养的东西——一个充满事件、背景、， 以及不断发展的洞察力。

存储库已从重命名 personal-mcp-core 到 orange-garden一些运行时名称仍然使用现有的Python包和CLI标识符， personal_mcp 和 personal-mcp，而项目概念和文档则以新名称移动。

软件盆景

盆景慢慢成形。它不是一次建成就完成的。

橙色花园也遵循同样的想法。生活产生小事件。事件通过注释获得上下文。注释累积成解释。解释变成了可视化、摘要和通知。人工智能代理是这一增长过程的一部分，但它们不是其中的中心。

该项目将个人数据视为可观察变化的长期记录：

events
  ↓
annotations
  ↓
interpretations (AI or human)
  ↓
visualization / notifications

这是一个开发人员存储库，用于仔细构建该基础，具有仅追加记录、明确边界和未来层成熟的空间。

橙色花园做什么

橙色花园为以下方面提供了基础系统：

• 记录个人生活和工作事件
• 将这些事件存储在持久的本地运行时中
• 附加标签、注释和后续注释
• 生成摘要和候选解释
• 通过仪表板和热图显示模式
• 通过本地或外部渠道发送通知
• 跟踪AI工作人员状态和协调
• 支持围绕共享事件历史的多代理编排

如今，事件层是存储库中最具体的部分。注释和解释被视为深思熟虑的下一层，而不是混合到原始事件存储中。

核心理念

1.判决前的观察

基础层存储可观察的事实，而不是分数或结论。意义属于更高层次。

2.仅附加历史记录

事件被记录为一个不断增长的时间线。后面的上下文应该与前面的事实一起添加，而不是重写它们。

3.状态变化比时间片更重要

该系统是围绕“发生了什么变化”而设计的，而不是恒定的时间跟踪。

4.AI是一层，而不是基底

人工智能工作者可以注释、解释、总结和通知，但底层记录应该在没有任何单一模型或代理运行时的情况下仍然有用。

5.本地第一个人可观察性

存储库假设个人数据应在本地环境中保持可理解和可操作性，只有在明确配置时才使用外部交付。

关于北极星的详细设计，请参见 文档/设计原则.md.

架构概述

在较高的层次上，橙色花园被组织成一小部分：

input surfaces
  CLI / HTTP / scripts / external logs
          |
          v
event tools and adapters
          |
          v
storage boundary
  local DB + recovery formats
          |
          v
higher-level outputs
  summaries / heatmaps / notifications / worker views / AI runtimes

从概念上讲，存储库已经包括：

• 事件日志和时间线访问
• 面向本地网络输入和热图的日常日志记录
• 摘要生成和候选提取
• 具有Discord功能的通知包装器
• 人工智能运行时观察的工人状态跟踪
• 支持代理驱动工作流的适配器和脚本

实现细节将继续发展，但架构方向是稳定的：事实在基础上，解释在上面，呈现在边缘。

技术结构见 docs/architecture.md.

工作流示例

示例流程如下：

1. Event
   "Wrote a design memo for the input flow"

2. Annotation
   tags: ["design", "ux"]
   context: "follow-up to heatmap input friction"

3. Interpretation
   "Most design work happens after small operational notes"

4. Output
   shown in a timeline, daily summary, heatmap, or notification

这种分离很重要：

• 事件保留了发生的事情
• 注释保留添加的上下文
• 解释保留了以后可能会改变的意义

活动合同本身记录在 docs/event-contract-v1.md.

仓库结构

存储库有意设计得较小且分层：

src/personal_mcp/
  server.py          CLI entrypoint
  adapters/          HTTP and MCP-facing adapters
  tools/             domain tools: events, summaries, workers, ingest
  storage/           storage boundary and persistence helpers
  core/              shared core helpers

docs/                design, architecture, contracts, workflows
scripts/             notification and automation helpers
tests/               focused test suite
data/                development/sample data only

当前领域和相邻功能包括：

• 个人和工作事件记录
• 情绪与一般音符捕捉
• 工程和工作日志记录
• 面向热图的每日输入流量
• 人工智能工作板/状态观察
• GitHub摄取和同步实用程序
• 通知传递方式 stdout 或Discord适配器

开发工作流程

存储库仍然是开发人员优先的。当前包和CLI名称保持不变：

• Python包： personal_mcp
• 控制台脚本： personal-mcp

最小设置：

python -m venv .venv
source .venv/bin/activate
make setup
make lint
make test

典型的本地运行循环：

export DATA_DIR="$HOME/.local/share/personal-mcp"

make run DATA_DIR="$DATA_DIR" PORT=8080
make log DATA_DIR="$DATA_DIR" TEXT="Wrote a short event"
make today DATA_DIR="$DATA_DIR"
make summary DATA_DIR="$DATA_DIR" DATE="$(date -u +%F)"

您还可以直接调用CLI：

python -m personal_mcp.server event-add "Wrote a short event" --domain worklog
python -m personal_mcp.server event-list --date "$(date +%F)"
python -m personal_mcp.server worker-status-set \
  --worker-id claude-1 \
  --worker-name Claude-1 \
  --terminal-id tty-1 \
  --current-issue '#324' \
  --status working
python -m personal_mcp.server worker-claim-state \
  --owner wakadorimk2 \
  --repo orange-garden \
  --issue-number 378 \
  --json
python -m personal_mcp.server worker-claim-post \
  --owner wakadorimk2 \
  --repo orange-garden \
  --issue-number 378 \
  --event-type claim \
  --worker-id codex-1 \
  --runtime codex \
  --reason "start claim baseline" \
  --dry-run

笔记：

• 运行时数据应位于存储库之外
• data/ 用于开发、测试和样品
• 运行时首先是本地的；外部通知传递是可选的

前端开发（附加步骤）

以上内容涵盖了Python的第一个正常工作流程。如果你正在使用React UI /app/，以下附加步骤适用。

开发人员（HMR）：

pnpm --dir frontend install
pnpm --dir frontend dev   # Vite dev server with HMR; access via Vite port directly

通过Python构建和服务：

pnpm --dir frontend install
pnpm --dir frontend build  # outputs to src/personal_mcp/web/app/
make run                   # Python server serves /app/ from the built artifacts

构建工件转到 src/personal_mcp/web/app/ （配置于 frontend/vite.config.ts). 它们被排除在Git之外，必须在打包之前重新构建。 看 docs/adapters.md 对于完整的构建工件合同。

缺少构建行为：

恢复：运行 pnpm --dir frontend build，然后重试。

CI：

这 frontend-build 工作在 .github/workflows/ci.yml 跑 pnpm install --frozen-lockfile 和 pnpm build 在每次推送和拉取请求中。它验证构建是否正确完成；它不打包或部署工件。

有用的文档

如果你想了解特定领域的当前真相来源，请从这里开始：

未来方向

橙色花园正朝着更完整的事件->注释->解释系统发展。

可能的方向包括：

• 一流的注释存储和检索
• 为AI代理提供更明确的解释管道
• 更丰富的仪表板和热图，用于长期模式读取
• 共享事件历史上更强的多智能体协调
• 更好地从外部工具和个人工作流程中获取信息
• 更严格但仍然可选的通知和审查循环

目标不是狭义的生产力仪表板。目标是一个持久的个人可观察性基质，可以随着生活、工作流程和一组代理的发展而增长。

隐私和许可

• 默认情况下，个人活动数据将保留在本地。
• 外部交付，如Discord webhooks，是明确的选择加入。
• 汇总报告和更广泛的集成应被视为可选层，而不是假设。
• 许可证状态仍在最终确定中。看 许可证.