Personal relationship CRM with interactive graph visualization. Zero dependencies · Local-first · AI-agent ready · MIT-licensed.
个人人脉关系管理系统，带交互式关系图可视化。 零依赖 · 本地优先 · 原生支持 AI 助手 · MIT 开源协议。
Your network is scattered across LinkedIn, phone contacts, chat apps, spreadsheets, and your head. When you need "an investor in NYC who knows fintech" you spend 15 minutes searching.
你的人脉散落在 LinkedIn、通讯录、微信、Excel 和大脑里。想找"深圳做投资的朋友"时，翻半天。
RN gives you / RN 给你：
- A tag-based system for organizing contacts / 一套标签系统管理联系人
- Natural-language search to find them instantly / 自然语言搜索瞬间找到对的人
- Path-finding through your network — who can introduce you to whom / 关系路径搜索 —— 谁能帮你搭线
- Interactive graph visualization — see your network as a force-directed graph / 交互式力导向关系图 —— 一眼看清你的人脉版图
- AI-agent integration — let your chat assistant pick up new contacts from conversation / AI 助手原生集成 —— 在聊天中自动识别人物 + 提示录入
- Local-only data, zero cloud, zero CDN / 数据 100% 本地，零云、零 CDN、零网络访问
# 1. Clone & install (zero deps) / 克隆 + 安装（零依赖）
git clone https://github.com/DannyAce66/Relationship_Network.git
cd Relationship_Network
pip install -e .
# 2. Try the bundled sample / 试用自带 10 人样例
python -m rn.cli --data-dir data list
# 3. Visualize / 生成可视化
python -m rn.cli --data-dir data visualize
# → open visualization/network.html in your browser
# → 用浏览器打开 visualization/network.htmlThe "owner" is you — the hub of your network. Default is Me.
"Owner"（拥有者）就是你自己 —— 关系图的中心节点。默认叫 Me。
# Linux / macOS
export RN_OWNER_NAME="Alex"
# Windows PowerShell
$env:RN_OWNER_NAME = "Alex"| Command 命令 | What it does 功能 |
|---|---|
rn add NAME --tags ... --rel ... |
Add or upsert a contact / 录入或更新联系人 |
rn find NAME |
Show one contact by name or alias / 按姓名/别名查一个人 |
rn search KEYWORD |
Full-text fuzzy search / 全文模糊搜索 |
rn list |
List all contacts / 列出所有联系人 |
rn link A B --rel "..." |
Create undirected relationship / 双向连接两人 |
rn unlink A B |
Remove relationship / 断开关系 |
rn path A B |
BFS shortest path (≤4 hops) / 找最短关系路径 |
rn neighbors NAME |
Immediate connections / 看某人的关系网 |
rn recommend "SCENARIO" |
Score contacts by scenario / 按场景推荐人选 |
rn discover "FREE TEXT" |
Surface possible new contacts from text / 从文本中发现新人 |
rn visualize |
Generate visualization/network.html / 生成关系图 HTML |
rn stats |
Quick overview / 总览统计 |
rn audit --tail N |
View write history / 看写操作历史 |
rn undo |
Roll back last write / 回滚上一次写入 |
rn remove NAME |
Delete a contact (careful!) / 删除联系人（小心！） |
Add --json to any command for machine-readable output (AI-agent friendly).
任何命令加 --json 输出结构化 JSON（AI 助手友好）。
python -m rn.cli visualize
# → opens visualization/network.html
# → 双击 visualization/network.html 用浏览器打开Single self-contained HTML file (data embedded), no CDN, no server. 单 HTML 文件（数据内嵌），无需 CDN、无需启动服务器。
Features / 特性:
- Force-directed layout auto-converges / 力导向布局自动收敛
- Node size scales with degree (hubs stand out) / 节点大小按连接数缩放，关键人物突出
- Hover for tooltip / 鼠标悬浮显示 tooltip（姓名/职业/标签）
- Click for right-panel detail / 点击节点看右侧详情面板
- Search bar highlights matching nodes / 搜索框高亮匹配节点
- Category filter in left panel / 左侧分类过滤一键孤立某圈子
- Drag-to-pin / double-click to release / 拖拽固定节点 / 双击释放
- Scroll zoom, drag empty space to pan / 滚轮缩放 / 空白处拖动平移
from rn import Store, Search, Graph, Person
store = Store() # auto-loads SOT / 自动加载真相源
# Add / upsert / 录入/更新
store.upsert(Person(name="Alice Chen",
tags=["VC", "AI"],
to_me_relation="investor friend"))
store.update("Alice Chen", add_tags=["NYC:#location"])
# Search / 搜索
results = Search(store).recommend("NYC AI investor", top_k=5)
# Relationships / 关系
store.link("Alice Chen", "Bob Wang", relation="co-investor")
path = Graph(store).find_path("Alice Chen", "Bob Wang")
# Aliases work transparently / 别名透明解析
store.update("Alice Chen", nickname="Ally / A.C.")
p = store.get("Ally") # → Alice Chen
# Rollback / 回滚
store.undo()| Feature 特性 | What you get / 你得到的 |
|---|---|
| Atomic writes / 原子写入 | tmp + rename — no half-written files / tmp 文件 + 重命名，不会留半成品文件 |
| Auto-backup / 自动备份 | Each write snapshots SOT (11 retained) / 每次写入自动快照（保留 11 份） |
| Audit log / 审计日志 | Every write recorded in JSONL / 每次写入记录在 audit.log |
| One-step undo / 一键撤销 | store.undo() restores most recent backup / 恢复到上次写入前的状态 |
| Healthcheck / 健康检查 | python -m tools.healthcheck (R11 invariants) / 7 项数据完整性自检 |
| Test suite / 测试套件 | 45 unit + invariant tests / 单元 + 不变量测试 |
RN ships with a complete agent guide at skills/SKILL.md and a constitution at RULES.md. Drop them into your agent's context (Claude Code, Hermes, Cursor, etc.) and it will know:
RN 自带完整的 agent 指南 skills/SKILL.md 和系统宪法 RULES.md。把它们放进你的 agent（Claude Code、Hermes、Cursor 等）的 context，它就会知道：
- When to scan conversations for new contacts (
Discovery.process) 何时在对话中扫描新人物 - When to ask the user for confirmation (always before writes) 何时向你确认（任何写操作前都要确认）
- Where to put each piece of information (full cheat sheet) 每条信息应该录到哪个字段（完整对照表）
- How to handle errors and roll back 如何处理错误、如何回滚
- How to interpret error codes for the user 如何把错误码翻译成自然语言告诉你
# Example for Claude Code / Claude Code 配置示例
cp RULES.md ~/.claude/skills/relationship-network/RULES.md
cp skills/SKILL.md ~/.claude/skills/relationship-network/SKILL.md{
"id": "8-char-uuid",
"name": "Alice Chen",
"nickname": "Ally / A.C.",
"tags": ["VC", "AI investing", "NYC:#location"],
"profiles": [
{"type": "职业", "content": "Sequoia AI partner"},
{"type": "能帮", "content": "intros to AI startups"},
{"type": "备注", "content": "..."}
],
"how_we_met": "TechCrunch 2024",
"to_me_relation": "investor friend",
"relations": [
{"person": "Bob Wang", "relation": "co-investor", "context": "Both at NeuralFlow"}
],
"meta": {
"first_met": "2024-09-18",
"last_updated": "2026-05-28",
"update_count": 3,
"category": "investor",
"status": "active"
}
}See SPEC.md for the full schema and RULES.md for usage conventions.
完整 schema 见 SPEC.md，使用规范见 RULES.md。
Relationship_Network/
├── RULES.md ← system constitution / 系统宪法（必读）
├── README.md ← this file / 本文件
├── LICENSE ← MIT
├── SPEC.md ← formal data spec / 数据规格
├── setup.py ← pip install
├── requirements.txt ← empty / 空（零依赖）
├── data/
│ ├── sample.jsonl ← 10 fictional contacts / 10 个虚构样例
│ └── .gitkeep
├── rn/ ← core library / 核心库
│ ├── models.py ← Person, RelationEdge, Profile
│ ├── store.py ← persistence (atomic, backed up, audited) / 持久化层
│ ├── search.py ← fuzzy / tag / scenario / 搜索
│ ├── graph.py ← BFS, neighbors, viz export / 图算法
│ ├── discovery.py ← name + tag extraction / 抽取人名 + 标签
│ ├── audit.py ← append-only log / 审计日志
│ └── cli.py ← `python -m rn.cli` entry / CLI 入口
├── tools/
│ ├── visualize.py ← generate HTML / 生成 HTML
│ └── healthcheck.py ← integrity self-test / 数据完整性自检
├── tests/
│ └── test_all.py ← 45 tests / 测试套件
├── visualization/
│ ├── _template.html ← template / 模板
│ └── network.html ← generated / 生成产物（不入仓库）
├── skills/
│ └── SKILL.md ← AI agent integration guide / agent 接口
├── docs/
│ └── GUIDE.md ← bilingual tutorial / 中英双语教程
├── migrations/ ← optional / 可选迁移历史
└── scripts/
└── install.sh ← one-click setup / 一键安装
MIT — see LICENSE.
Reliability hardening from real-world daily use / 来自真实日常使用的可靠性强化：
store.normalize()self-heal / 自愈方法: folds alias relation-peers back to canonical, drops self-loops, dedupes, and symmetrizes one-way edges. Idempotent — fixes the drift that accumulates after undo/restore crossing a rename, or one-directional agent writes. 折叠别名关系、删自环、去重、对称化单向边。幂等，修复 undo/改名/单向写入累积的漂移。- Empty-update short-circuit / 空更新短路:
update()with no real change no longer writes a backup or audit entry — eliminates backup-directory churn. 无实际变化的 update 不再写备份/审计，消除备份目录刷屏。 - Owner node legalized / owner 节点合法化: the owner may now exist as a single Person (sentinel id
OWNER) so the hub node shows their own profile; healthcheck/invariants updated accordingly. owner 可作为 sentinel id 的 Person 存在，hub 节点显示本人 profile。 - Symmetry check excludes owner edges / 对称检查排除 owner 边: owner relationships live in
to_me_relation, so they're correctly one-way. - 2 new tests (empty-update, normalize) + updated invariants. / 新增 2 测试 + 更新不变量。
Major rewrite from v0.3.x / 相对 v0.3.x 的大重构：
- New schema / 新 schema: nested
profiles+ inlinerelations(was: flat columns) 嵌套式profiles+ 内联relations（旧：扁平字段） - JSONL is the only storage / JSONL 单一存储: SQLite backend dropped; safer & more portable SQLite 后端废弃，更安全更易迁移
- Force-directed visualization / 力导向可视化: was none 全新交互式关系图（v0 没有可视化）
- Safety / 安全机制: atomic writes, auto-backup, audit log,
undo()(was: none) 原子写入、自动备份、审计日志、撤销（v0 没有） store.rename()/merge(): handles canonical-name changes & duplicates 支持改名与合并重复人物，自动重写所有反向引用OWNER_NAMEconfigurable / OWNER 可配置: via env var (was: hardcoded) 通过环境变量自定义（旧：写死）- Healthcheck tool / 健康检查工具: enforces 7 data integrity invariants 7 项数据完整性自动校验
- 45 tests / 45 个测试: unit + invariant + sample-data smoke 单元 + 不变量 + 样例数据冒烟
RULES.mdconstitution / RULES.md 宪法: agents now have explicit hard rules to follow AI 助手现在有明确的硬规则可循skills/SKILL.md/skills/SKILL.md: standardized AI-agent integration interface 标准化的 AI 助手集成接口
See docs/GUIDE.md for the full bilingual tutorial including v0 migration notes. 完整中英双语教程（含 v0 数据迁移说明）见 docs/GUIDE.md。