Substrate

One private place all your AI assistants share — so every one of them knows who you are and what you've saved.

一个你私有、所有 AI 助手共用的地方——让它们每一个都认识你、都知道你存过什么。

You probably use several AIs now — Claude on your laptop, a chatbot on your phone, maybe one on a server. Normally each is a stranger: you re-explain yourself every time, and whatever you tell one, the others never learn. Substrate gives them a shared memory and knowledge base that you own. Tell any of them "remember this," "save that restaurant," "note this down" — and it lands in one private folder that all of them can read and write. Under the hood it's just plain text files in a Git repo: yours forever, movable anywhere, locked into no app.

你现在大概在用好几个 AI——电脑上的 Claude、手机上的聊天机器人、也许还有服务器上的。平时它们互不相识:你得对每个重新介绍自己,告诉这个的事那个永远不知道。Substrate 给它们一个你自己拥有的共享记忆 + 知识库。对任何一个说*「记住这个」、「收藏这家餐厅」、「记一下」*,它就落进同一个私有文件夹,所有 AI 都能读写。底层就是 Git 仓库里的纯文本文件:永远是你的、能搬到任何地方、不被任何 app 锁住。

What it feels like:

• 9 am, on your phone — you tell the chat assistant: "Remind me — dentist next Wednesday 3 pm. And save this Sichuan place, it was great."
• 11 pm, on your laptop — you ask the coding agent: "What's left this week?" The dentist is in its answer, and the restaurant is already on your list. You never repeated a word — they read (and write) the same repo.

用起来像这样:

• 早上 9 点,手机上——对聊天助手说:「提醒我下周三下午 3 点看牙。另外这家川菜馆记一下,很不错。」
• 晚上 11 点,电脑上——问编程 agent:「这周还有什么没做?」——回答里就有看牙这条,餐厅也已经进了你的清单。一个字没重复,因为它们读写的是同一个仓库。

This repo is the reusable template (the "engine"). You don't put your data here — you use it to spin up your own private copy, where your notes actually live:

这个仓库是可复用的模板(也就是"引擎")。你的数据不放在这里——你用它生成一份自己的私有副本,笔记存在那份里:

                you 你
       "remember this" 「记一下」
                  │
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
Claude Code     Hermes       Codex …    ← your agents 你的各个 agent
    └─────────────┼─────────────┘
          read & write 共读共写
                  ▼
┌──────────────────────────────────┐
│  YOUR INSTANCE — private git repo│  ← memory / knowledge / collections /
└──────────────────────────────────┘    todo / skills… 全是纯 Markdown
                  ▲
   scaffolded & upgraded by 生成与升级
                  │
┌──────────────────────────────────┐
│  SUBSTRATE ENGINE — this repo    │  ← mechanism only 只有机制,无用户数据
└──────────────────────────────────┘

---

What you can do with it

• Tell it once, every AI knows. "I'm vegetarian," "my job is X," "I prefer Y" — saved once, shared by all your assistants. Stop re-introducing yourself to each new chat.
• Save the things you'd otherwise lose. Facts worth keeping, restaurants worth remembering, books to read, running to-dos — just say "save this" and your AI files it, and links it to related notes so you can find it again.
• Agents start every session already knowing you. Wire the standing-context layer once (default for chat assistants like Hermes; opt-in for coding agents) and each session begins pre-loaded with your core memory, a map of what's in the repo, and a "when to use which skill" router — the agent uses your base proactively instead of waiting to be asked. However much you accumulate, the injected digest stays small: a distilled core plus an index, details read on demand.
• It offers to remember, so you don't have to say "save this." The house rules injected with that standing context teach the agent to notice stable facts, decisions, to-dos, and things you want to try in normal conversation, and to propose saving them — one light note after answering, never writing without your OK, and it backs off when you say stop.
• It keeps itself tidy — and safe. New notes get auto-linked to related ones; a built-in health check catches broken links, drifted indexes, and contract violations — and scans for accidentally committed secrets, so credentials never slip into Git.
• You own it, fully. Everything is plain Markdown in your own private Git repo. Back it up, read it by hand, open it directly as an Obsidian vault, move it anywhere — no lock-in, no cloud you don't control.

你能拿它干什么

• 说一次,所有 AI 都知道。 「我吃素」「我做的是 X」「我偏好 Y」——存一次,所有助手共享。不用再对每个新对话重新自我介绍。
• 存下那些本来会丢的东西。 想留的事实、值得记住的餐厅、想读的书、没做完的待办——说句「存一下」,AI 就帮你归档,还链到相关笔记,方便以后找回。
• agent 开工就认识你。 接一次「常驻上下文」(对话型助手如 Hermes 默认接;编程 agent 按需选接),此后每个 session 一开始就自动带着你的核心记忆、库里有什么的地图、以及「什么话该用哪个 skill」的路由表——agent 会主动用你的库,而不是等你想起来问。而且记忆攒得再多,注入的小抄也恒定小:蒸馏的核心 + 一份目录,细节按需现读。
• 它会主动提出帮你记——你不用每次说「存一下」。 随常驻上下文注入的房规,教会 agent 在正常对话里识别稳定事实、决定、待办、想试的东西,答完后轻轻问一句要不要存——绝不擅自写库,你说别问了它就不再问。
• 它自己保持整洁,也保持安全。 新笔记自动链到相关的;内置体检抓断链、索引漂移、契约违规——还会扫描误提交的密钥/凭据,不让红线内容溜进 Git。
• 完全属于你。 全是你私有 Git 仓库里的纯 Markdown。能备份、能手翻、能直接当 Obsidian vault 打开、能整体搬走——不锁定、不依赖你管不到的云。

---

How it's different

It's not another note-taking app, and not a single chatbot with memory bolted on. It's the layer underneath: the place your data lives and that any AI can plug into.

它跟已有的东西差在哪

它不是又一个笔记 app,也不是某一个加了记忆的聊天机器人。它是底下那一层:你数据的归属地,任何 AI 都能接进来。

	Built-in AI memory · 自带记忆 (ChatGPT/Claude)	Agent's own memory · agent 框架自带记忆 (Hermes/OpenClaw…)	Note apps · 笔记软件 (Obsidian/Notion…)	Substrate
Who shares it · 谁共享	that one app only · 只有那一个 app	that one agent, on that one machine · 只有那台机上的那一个 agent	you, manually · 靠你自己翻	every agent you run · 你所有的 agent
Who maintains it · 谁维护	vendor's black box · 平台黑箱	that agent, ad hoc — no shared rules, checks, or migrations · 该 agent 随手记,无共同房规/体检/迁移	you · 你手动	your agents, under house rules · 各 agent 按房规共维
Yours to keep? · 数据归属	locked in · 锁在平台里	local files, but one silo per agent, in framework shape · 本地文件,但按框架各存一份、互不相通	varies by app · 看 app	plain files + Git, fully yours · 纯文件 + Git,完全是你的

"But Hermes / OpenClaw already remember things?" They do — and that's per-agent working memory: it lives with that one agent on that one machine, in that framework's own shape; your other agents never see it, and nothing checks or migrates it. Substrate doesn't replace it — it sits underneath and feeds it: on Hermes, for example, Substrate injects your core memory + repo map through Hermes's own context-file mechanism. Each agent keeps its scratchpad; the durable, cross-agent truth lives in your instance repo.

「可 Hermes / OpenClaw 不是自己就有记忆吗?」 有——那是单 agent 的工作记忆:跟着那台机上的那一个 agent 走、存成那个框架自己的样子;你的其它 agent 看不见它,也没有任何机制体检或迁移它。Substrate 不取代它,而是垫在下面喂它——比如在 Hermes 上,Substrate 正是借 Hermes 原生的 context-file 机制把你的核心记忆 + 库地图注入进去的。每个 agent 留着自己的草稿本;跨 agent 共享的长期事实,住在你的实例仓库里。

---

Quick start

You'll end up with two git repos: the engine (this one, public, mechanism only) and your instance (private, holds your knowledge / memory / skills / lists).

你会有两个 git 仓库:引擎(这个,公开,只含机制)+ 你的实例(私有,放你的知识/记忆/技能/清单)。

Option A — let your agent set it up (recommended)

Hand the engine URL + the prompt below to any agent that can run shell commands (Claude Code, Codex, Hermes, …). It does the whole setup for you.

方式 A —— 让你的 agent 帮你搭(推荐)

把引擎地址 + 下面这段 prompt 丢给任何能跑 shell 的 agent(Claude Code、Codex、Hermes…),它会替你把整套搭好。

I want to set up a personal knowledge base using the Substrate engine:
https://github.com/wheam/substrate

Please do it for me, and STOP and tell me if any step fails (don't silently continue):
1. Check prereqs: git + python3 (>=3.8) exist, and git is authenticated to GitHub
   (`gh auth status`, or an SSH key, or an HTTPS token). If auth is missing, stop and
   tell me how to set it up — clone/push will dead-end without it.
2. Clone the engine to a temp dir and read its README.
3. Ask me for: where to put my instance, a short instance name, my GitHub username.
4. Scaffold my private instance: run ./init-instance.sh <dir> <name>, then inside it:
   `git init && git add -A && git commit -m "init" && git branch -M main`
   (the branch rename keeps step 7 working on machines whose git default isn't main).
5. Install the maintenance skills into YOUR runtime:
   python3 <instance>/skills/substrate-sync/sync.py --src <instance>/skills --runtime <your-runtime> --apply
   VERIFY at least one skill was actually installed — sync now WARNs and exits non-zero if
   --src has no skills. If 0 were installed, the --src path is likely wrong (point it at
   <instance>/skills), or --runtime doesn't match your agent — stop and ask me.
6. Run substrate-doctor on the instance:
   python3 <instance>/skills/substrate-doctor/doctor.py <instance>
   If it reports any ERROR, stop and show me.
6b. (Only if YOUR runtime is a conversational assistant like Hermes — skip for code-focused
   runtimes such as Claude Code / Codex) Wire standing-context injection so you auto-load my
   memory + repo map + an intent→skill router every session, instead of waiting to be asked:
   see adapters/<your-runtime>/README.md (the `substrate-runtime-context` section).
7. Create a PRIVATE GitHub repo under my username (e.g. `gh repo create <username>/<name> --private`),
   add it as the remote, and `git push -u origin main`.
   VERIFY the push actually succeeded — a local-only instance silently disables all
   multi-machine sync. If you can't push, stop and tell me exactly what to fix (auth).
8. Onboard yourself on the instance: read <instance>/governance/bootstrap.md and follow it
   (constitution + zones, set your local identity) — install alone isn't check-in.
9. Give me a few example phrases to start using it.

Never put any of my personal content into the public engine repo.

Option B — manual (4 steps)

方式 B —— 手动 4 步

Prereqs / 前置: git authenticated to GitHub (gh auth login, or an SSH key, or an HTTPS token — you'll push your instance to a private repo, so set this up first), python3 ≥ 3.8 (standard library only — no pip installs), and an agent runtime that can read skills.

前置：git（先认证到 GitHub——gh auth login / SSH key / HTTPS token，因为下一步要把实例推到私有仓库，没认证会卡在 clone/push）、python3 ≥ 3.8（仅标准库，无需 pip）、一个能读 skill 的 agent runtime。

# 1) Get the engine (or fork it to your account first)
git clone https://github.com/wheam/substrate.git && cd substrate

# 2) Scaffold your private instance (self-contained: template + vendored skills + adapters)
./init-instance.sh ~/my-substrate my-instance
cd ~/my-substrate && git init && git add -A && git commit -m "init my substrate instance" && git branch -M main
#   Then create a PRIVATE GitHub repo and push it (your content stays private)

# 3) Install the maintenance skills into your runtime
python3 ~/my-substrate/skills/substrate-sync/sync.py \
        --src ~/my-substrate/skills --runtime claude-code --apply
#   Swap --runtime for codex / hermes / … (see adapters/)
#   NOTE: claude-code, generic-filesystem and hermes are verified on real hardware (hermes:
#   both skill install and standing-context injection). codex's install path is verified too,
#   but Codex-side auto-discovery isn't end-to-end certified yet — after install, verify the
#   skill actually landed where your agent reads skills from.

# 4) Onboard your agent: tell it "get set up on my personal repo"
#    → triggers substrate-bootstrap (reads the constitution + zones, sets identity, self-checks)
#    For a chat assistant (Hermes-like), also say "wire the standing context"
#    → substrate-runtime-context makes it know you from the first message of every session

That's it — you now have a multi-agent, git-native, migratable personal state layer. On a new machine or agent, just git clone your instance and re-run step 3.

完工——你就有了一个多 agent 共维、git 原生、可迁移的个人状态层。换机器/换 agent,只要 git clone 你的实例 + 重跑第 3 步即可。

---

Daily use — talk to your agent

Once installed, use plain language; your agent triggers the right skill.

日常使用 —— 和你的 agent 对话

装好后用自然语言,agent 会触发对应 skill。

You say / 你说	Skill
"note this / save to my knowledge base" · 「记一下 / 存进知识库」	substrate-curator
"save this restaurant / add to my book list" · 「收藏这家餐厅 / 加到书单」	substrate-collections
"remember that I… / my preference is…" · 「记住我… / 我的偏好是…」	substrate-memory
"add a todo / what's left" · 「加个待办 / 还有啥没做」	substrate-todo
"should I save this / where does it go" · 「这个要不要存 / 存哪」	substrate-intake
"import these notes / this vault" · 「把这些笔记导进库」	substrate-import
"make my agent auto-use the repo / wire standing context" · 「让 agent 主动用我的库 / 接常驻上下文」	substrate-runtime-context
"health-check my repo" · 「体检一下库」	substrate-doctor
"install / align skills" · 「装 / 对齐 skill」	substrate-sync

---

It maintains itself

A shared base rots unless someone maintains it. Here the "someone" is the agents themselves, held to mechanisms:

• Standing context stays fresh — event-driven, no timers. After any agent writes to the repo, it regenerates the injected digest on the spot; a git pull at the start of a session brings in what your other machines wrote before the repo is used. No daemons, no cron jobs, no background hooks.
• Session-start self-check. Have your agent open each session with: git pull → substrate-sync --check → if behind, --apply → substrate-doctor. --check does a best-effort git fetch and flags when you're behind the remote, so a silently-failed pull can't masquerade as "up to date." A copy-pasteable Claude Code SessionStart hook ships in adapters/claude-code/README.md; for other runtimes see template/governance/bootstrap.md.
• CI out of the box. Instances scaffolded from the template ship with a GitHub Actions workflow that runs doctor on every push — rot shows up as a red ✗ in your own repo, not months later.
• Concurrent writes don't corrupt. When two machines append to the same list at once, row tables auto-merge (.gitattributes union) instead of conflicting; for everything else a written protocol applies — rebase, keep both sides + mark contested, never force-push.
• Doctor, the anti-rot check. Read-only and zero-dependency (pure python3 stdlib): broken links, orphans, index drift, schema/contract violations, engine-version skew across machines — plus a red-line scan for committed secrets and credentials.
• Upgrades run like database migrations — no data loss. Ordered, idempotent, verifiable, reversible (git-tag snapshot + before/after doctor checks; multi-machine fleets migrate only on the device flagged migration_leader). When the engine ships a new version, in your instance:

/path/to/substrate/init-instance.sh --refresh ~/my-substrate   # refresh vendored skills
#   then: tell your agent "upgrade my repo" → triggers substrate-migrate

它自己维护自己

共享库没人维护就会烂。这里的"人"是 agent 自己,由机制兜底:

• 常驻上下文保持新鲜——事件驱动,无定时器。 agent 每次写完库就地重新生成注入的小抄;每次开工先 git pull,把别的机器写的内容在用库前带进来。没有守护进程、没有 cron、没有后台钩子。
• 开工自检。 让 agent 每个 session 先跑:git pull → substrate-sync --check → 落后则 --apply → substrate-doctor。--check 会顺带 git fetch 比对远程、本地落后也能发现,静默失败的 pull 冒充不了"已最新"。Claude Code 的现成 SessionStart hook 模板在 adapters/claude-code/README.md;其它 runtime 见 template/governance/bootstrap.md。
• CI 开箱即有。 从模板脚手架出的实例自带 GitHub Actions 工作流,每次 push 自动跑 doctor——库烂了在你自己仓库里红一个 ✗,而不是几个月后才发现。
• 并发写不脏库。 两台机器同时往同一张清单追加时,行式主表自动合并(.gitattributes union)、不出冲突;其余情况有成文协议——rebase、两边都保留并标 contested、绝不 force-push。
• doctor 防退化体检。 只读、零依赖(纯 python3 标准库):断链、孤儿页、索引漂移、schema/契约违规、多机引擎版本错位——外加红线扫描:误提交的密钥/凭据。
• 升级当数据库迁移做——绝不丢数据。 有序/幂等/可验证/可回滚(git tag 快照 + doctor 前后校验;多机只在标了 migration_leader 的机器上跑)。引擎发新版后,在你的实例里跑上面那两步(先刷新 vendored skill,再让 agent「升级库」)。

---

The core idea: Engine / Instance separation

This split is what lets the engine be open while your content stays private.

核心:Engine / Instance 分离

正是这个拆分,让引擎可以开源、而你的内容保持私有。

	Engine (this repo, public)	Instance (your private repo)
Holds / 内容	mechanism, template, schemas, reference skills, adapters, migrations	knowledge, collections, memory, todos, projects, fleet, private skills
Constraint / 约束	must not depend on any user's incidental facts	your stuff, layered on top of the engine

The engine decides how to maintain; your instance decides what to maintain. They are two independent git repos. The engine is also runtime-neutral: declarative adapters ship for claude-code, generic-filesystem and hermes (all verified on real hardware — hermes including standing-context injection), codex (install path verified; agent-side auto-discovery still pending) — plus obsidian as a view layer: your instance opens directly as a vault, zero migration.

引擎决定"怎么维护",实例决定"维护什么"。两者是两个独立的 git 仓库。引擎同时不绑死任何 runtime:声明式 adapter 现有 claude-code、generic-filesystem、hermes(均已真机验证,hermes 含常驻注入)、codex(安装路径已核实,agent 端自动发现待验证)——另有 obsidian 作为视图层:你的实例直接当 vault 打开,零迁移。

---

Learn more / Contributing

• Concepts & design: docs/concepts.md, docs/architecture.md
• Full design + roadmap: docs/BUILD-PLAN.md
• Hacking on the engine itself: CONTRIBUTING.md (red lines, contract-first, skills-first, self-checks)
• Run the tests: sh tests/run-tests.sh (zero-dependency)

了解更多 / 参与开发

概念与设计见 docs/;想给引擎本身写代码看 CONTRIBUTING.md;测试 sh tests/run-tests.sh(零依赖)。

License

MIT — see LICENSE.