Cairn

Cairn

一款会记住你做过什么的工作追踪工具。它会记录你的编码会话、操作过的文件、从待办到完成的任务以及项目笔记，然后将这些内容集中在一处，并生成每日和每周汇总。这个名字指的是标记路径的石堆。

Cairn 作为多租户 Web 应用运行在 Vercel 上，并使用 Neon Postgres 数据库。每个账户都可以注册和登录，且只能看到自己的数据。

构建方式

整个服务仅使用 Python 标准库和一个依赖项（psycopg）。不使用框架。

• api/index.py — Vercel 无服务器入口。Vercel 的 Python 运行时会将其视为兜底入口，因此所有请求都会到达这里。
• lib/handler.py — 路由。相同的 BaseHTTPRequestHandler 有三种运行方式：Vercel 函数、本地开发服务器和测试。
• lib/data.py — 所有 SQL 语句，每条语句都按 user_id 限定范围。
• lib/db.py — Neon 连接（连接池端点）和一些小型查询辅助函数。
• lib/auth.py — PBKDF2 密码哈希、会话和令牌解析。
• lib/limits.py — 注册/登录速率限制和每个账户的配额上限，二者均由 Postgres 支持。
• lib/assets.py — 单页应用和 favicon，以 base64 嵌入，随函数包一起发布。由 build_assets.py 生成；编辑 static/ 后请重新运行该脚本。

本地开发

你需要一个可连接的 Postgres。用 Docker 启动一个临时数据库即可：

docker run -d --name cairn_pg -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=cairn -p 5432:5432 postgres:16-alpine
python3 -m venv .venv && .venv/bin/pip install 'psycopg[binary]'
export DATABASE_URL="postgres://postgres:[email protected]:5432/cairn"
.venv/bin/python dev.py --init    # create the schema, then serve on :8765

测试会使用同一个数据库：

.venv/bin/python tests/smoke.py        # core CRUD + isolation
.venv/bin/python tests/test_limits.py  # rate limiting + quotas
.venv/bin/python tests/test_sp3.py     # file activity + filtered lists

部署

推送到 main 后，会通过 Vercel GitHub 集成部署到生产环境。DATABASE_URL 和其他 Neon 变量来自 Vercel ↔ Neon 集成；应用会读取连接池连接字符串。架构变更通过 initdb.py，使用直接（非连接池）URL 应用。

Agent 端

agent/ 文件夹包含 MCP 服务和两个在你的计算机上运行的 Claude Code 钩子。它们使用你的账户令牌，通过 HTTPS 与此 API 通信，因此 Claude Code 执行的所有操作都会流入你的 Cairn 账户。该服务会向 Claude 提供一组 cairn 工具；钩子则会自行记录会话和文件编辑。

在 Claude Code 中，最快的安装方式是使用插件 — 此仓库同时也是一个插件市场（.claude-plugin/marketplace.json）：

/plugin marketplace add https://github.com/cybort360/cairn
/plugin install cairn@cairn

这会配置 MCP 服务和两个钩子；你只需将令牌保存到 ~/.cairn_token（需要将 uv 添加到 PATH 中）。手动安装方式 — 克隆、创建 venv、运行 claude mcp add — 见 agent/README.md。Web 应用的部署会忽略 agent/；它仅在客户端运行。

设计说明

构建 Cairn 的每个子项目在 docs/superpowers/specs/ 下都有一份规范：云端核心、身份验证加固以及本地 Agent 切换。如果你想了解某项决策背后的原因，而不只是查看代码，可以阅读这些规范。