relation-keeper

维护、记忆、提醒你的社交关系。用于：(1) 记录和累积人物肖像（性别、出生年/日、家庭地址、手机、一起做过的事等）， (2) 记录未来的约会、纪念日、生日并设置分级提醒，(3) 归档过去共同经历（约会、吃饭、游玩等）， 以便后续查询某人时能回溯。

Security Scan

The skill's code, install steps, and declared configuration are consistent with a local relationship/reminder manager that stores PII and schedules periodic scans; nothing in the package indicates hidden exfiltration or unrelated credential access.

Purpose & Capability

Name/description match the implemented behavior: storing portraits, past/future events, and scanning for reminders. Required files, scripts, and optional env vars (RELATION_KEEPER_DATA, RELATION_KEEPER_TZ, RELATION_KEEPER_CHANNEL) are appropriate for this purpose.

Instruction Scope

Runtime instructions and scripts read/write JSON files under the skill data directory, parse user input, and print reminder messages. They do not access other system config or network endpoints. Note: the skill records sensitive personal data (names, phones, addresses) locally and will output reminder text to OpenClaw sessions or a configured channel.

Install Mechanism

Installation is a local npm postinstall that runs scripts/install.js to create data files and call the 'openclaw' CLI to add a cron. There are no remote downloads or external package installs beyond running npm scripts and Node.js usage, which is proportionate for the stated purpose.

Credentials

No secret credentials are required. Declared environment variables (DATA dir, TZ, CHANNEL) are reasonable. If RELATION_KEEPER_CHANNEL is set (e.g., telegram:CHAT_ID), reminders will be routed to that channel (the skill itself does not request tokens; it delegates to platform/Gateway). Consider whether exposing PII to the configured channel is acceptable.

Persistence & Privilege

The skill is not always-enabled and uses normal autonomous invocation. The install script attempts to register a periodic cron task via the openclaw CLI (expected for scheduling reminders) and does not modify other skills or system-wide configs beyond adding a cron entry.

Assessment

This skill is coherent with its description, but it stores sensitive personal information (names, phone numbers, addresses, birthdays) as JSON files in the skill data directory (by default relation-keeper/data, or $RELATION_KEEPER_DATA if set). Installing will run a postinstall script that tries to register a cron job with the local OpenClaw CLI to run scan.js every 15 minutes; ensure you trust and have OpenClaw installed. If you set RELATION_KEEPER_CHANNEL (e.g., telegram:CHAT_ID), reminders will be pushed to that channel — confirm that the channel recipient and platform gateway are secure before enabling. If you want more assurance, review the scripts (they are included) and consider placing RELATION_KEEPER_DATA in a protected directory or keeping backups/encryption for stored PII. If you prefer not to auto-register a cron, skip postinstall and run npm run install:cron manually after review.

关系维护 Relation Keeper

维护你的社交关系网络：肖像维护、未来提醒、过去归档。

---

一、数据存储

数据存储在 $RELATION_KEEPER_DATA 指向的目录；未设置时使用当前 skill 目录下的 data/ 文件夹。

1.1 人物肖像 portraits.json

{
  "people": {
    "张三": {
      "name": "张三",
      "aliases": ["老张"],
      "gender": "男",
      "birthday": "03-15",
      "birthYear": 1990,
      "birthDate": "1990-03-15",
      "address": "北京市朝阳区xx路xx号",
      "phone": "+86 138****1234",
      "notes": "大学同学，做金融",
      "updatedAt": "2026-02-05T10:00:00Z",
      "facts": [
        { "key": "喜好", "value": "喜欢钓鱼", "source": "2026-01-20 聊天", "at": "2026-01-20" },
        { "key": "职位", "value": "某银行经理", "source": "2026-01-20", "at": "2026-01-20" }
      ]
    }
  }
}

• 每次用户提及某人及与其相关的事件、信息时，更新对应 portrait。
• gender：性别（男/女/其他）。
• birthday：MM-DD 格式，用于周年提醒。
• birthYear：出生年（数字），可选。
• birthDate：出生日期，可模糊，如 "1990"、"1990-03"、"1990-03-15"。
• address：家庭地址。
• facts 为键值对列表，可按 key 去重或追加（同一 key 保留最新一条）。

1.2 过去事件 past_events.json

{
  "events": [
    {
      "id": "evt-001",
      "personIds": ["张三", "李四"],
      "type": "吃饭",
      "date": "2026-01-18",
      "summary": "和张三、李四在海底捞聚餐",
      "details": "讨论创业想法",
      "createdAt": "2026-02-05T10:00:00Z"
    }
  ]
}

• type：吃饭、约会、游玩、聚会、会议等。
• 查询某人时，可基于 personIds 过滤并返回相关 past_events。

1.3 未来事件 future_events.json

{
  "events": [
    {
      "id": "fevt-001",
      "personIds": ["张三"],
      "type": "生日",
      "date": "2026-03-15",
      "time": null,
      "summary": "张三生日",
      "reminderRule": "birthday",
      "createdAt": "2026-02-05T10:00:00Z"
    },
    {
      "id": "fevt-002",
      "personIds": ["李四"],
      "type": "约会",
      "date": "2026-02-10",
      "time": "18:30",
      "summary": "和李四晚餐",
      "reminderRule": "appointment",
      "createdAt": "2026-02-05T10:00:00Z"
    }
  ]
}

• reminderRule：
  • birthday：生日/纪念日规则
  • appointment：约会规则

---

二、提醒规则：单一扫描任务

不创建一次性提醒，使用一个每 15 分钟运行的 Cron 调用 scan.js 扫描，如有需要提醒的内容则输出。

2.1 提醒规则

事件类型	提醒时机
生日 / 纪念日	7 天前、3 天前、当天（每年按 MM-DD 匹配）
约会	事件前 2 小时、事件当刻

2.2 定时任务自动配置

安装本 skill 时，执行 npm install 会自动运行 postinstall 脚本，调用 node scripts/install.js 配置定时任务。用户无需手动执行 openclaw cron add。

若自动配置失败，可手动运行：

cd <skill 目录> && npm run install:cron

2.3 scan.js 行为

• 读取 portraits.json（生日 MM-DD）与 future_events.json
• 生日/纪念日：按 MM-DD 每年匹配，检查当天、+3 天、+7 天
• 约会：检查当前时间是否落在「事件前 2h」或「事件当刻」窗口内
• 已发送的提醒记录在 reminders_sent.json，避免重复

2.4 添加未来事件时

仅需写入 future_events.json，无需创建任何 Cron。扫描任务会自动发现并提醒。

---

三、技能行为指南

3.1 何时触发本 skill

• 用户提及某人及与其相关的信息、事件。
• 用户说「记一下」「提醒我」「某人生日」「和某人约会」等。
• 用户问「我和张三之前做过什么」「张三喜欢什么」「下周有什么安排」等。

3.2 肖像维护

• 解析用户输入中的人名、事件、属性（年龄、手机、喜好等）。
• 更新 portraits.json：新建或合并到已有 portrait，追加 facts。
• 若事件属于「过去」，同时写入 past_events.json。

3.3 未来事件与提醒

• 解析日期、时间（支持自然语言，如「下周五晚上 6 点半」）。
• 确定 reminderRule：生日/纪念日用 birthday，具体时间约会用 appointment。
• 写入 future_events.json 即可，扫描任务每 15 分钟会自动发现并提醒。
• 向用户确认：「已记录，到时会提醒你。」

3.4 过去事件归档

• 用户描述「上周和谁吃饭」「昨天和谁约会」时，写入 past_events.json。
• 关联 personIds，便于按人查询。

3.5 查询

• 「张三的信息」→ 读取 portraits.json 中 张三，并可选汇总 past_events 中与之相关的事件。
• 「我和张三一起做过什么」→ 查询 past_events 中 personIds 包含张三的事件。
• 「近期有什么社交安排」→ 查询 future_events.json 未来 N 天内事件。

---

四、配置

在 shell 或 ~/.openclaw/.env 中：

# 数据目录（可选，未设置时使用 skill/data/）
export RELATION_KEEPER_DATA="$HOME/.openclaw/relation-keeper"

# 时区（用于计算提醒时间）
export RELATION_KEEPER_TZ="Asia/Shanghai"

# 提醒发送渠道（可选）
# 配置则直接推送到该渠道，如: export RELATION_KEEPER_CHANNEL="telegram:YOUR_CHAT_ID"
# 未配置则推送到当前聊天（main session）
export RELATION_KEEPER_CHANNEL=""

---

五、自然语言触发示例

用户说	技能动作
张三生日 3 月 15 号，记一下	更新 portrait 生日，创建 future_event + birthday 提醒
下周五晚 6 点半和李四吃饭	创建 appointment，设置 2h 前 + 当刻提醒
上周和张三在海底捞吃过饭	写入 past_event，更新 portrait
张三喜欢钓鱼	更新 portrait.facts
张三的电话是 138xxxx1234	更新 portrait.phone
张三是男的 / 张三性别	更新 portrait.gender
张三 1990 年出生	更新 portrait.birthYear / birthDate
张三住朝阳区xx路	更新 portrait.address
我和张三做过什么	查 past_events，汇总输出
张三是谁 / 张三的信息	输出 portrait + 相关 past_events 摘要
近期有什么约会 / 生日	查 future_events 未来 7–14 天

---

六、脚本与工具

从 skill 根目录（relation-keeper/）运行，需 Node.js 16+：

# 人物肖像
node scripts/portrait.js get 张三
node scripts/portrait.js upsert 张三 --birthday 03-15 --gender 男 --birthYear 1990 --address "北京市朝阳区xx路" --fact-key 喜好 --fact-value 钓鱼

# 事件
node scripts/events.js future-add --persons 张三 --type 生日 --date 2026-03-15 --summary "张三生日" --rule birthday
node scripts/events.js past-add --persons "张三,李四" --type 吃饭 --date 2026-01-18 --summary "海底捞聚餐"

# 扫描提醒（通常由 Cron 每 15 分钟调用，也可手动执行测试）
node scripts/scan.js

# 配置定时任务（安装时自动执行，也可手动运行）
npm run install:cron