{"id":50718613,"url":"https://github.com/ggshr9/hearth","last_synced_at":"2026-06-09T21:30:35.028Z","repository":{"id":353775416,"uuid":"1220778650","full_name":"ggshr9/hearth","owner":"ggshr9","description":"Tend your second brain. A personal AI runtime for your plain-markdown vault — Karpathy LLM Wiki pattern, chat-first, agent-agnostic.","archived":false,"fork":false,"pushed_at":"2026-04-25T14:22:09.000Z","size":122,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T14:25:53.132Z","etag":null,"topics":["acp","agent-runtime","claude-code","karpathy-llm-wiki","markdown","obsidian","personal-knowledge-base","second-brain"],"latest_commit_sha":null,"homepage":"https://tendhearth.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ggshr9.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-25T10:16:46.000Z","updated_at":"2026-04-25T14:22:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ggshr9/hearth","commit_stats":null,"previous_names":["ggshr9/hearth"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ggshr9/hearth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggshr9%2Fhearth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggshr9%2Fhearth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggshr9%2Fhearth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggshr9%2Fhearth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ggshr9","download_url":"https://codeload.github.com/ggshr9/hearth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggshr9%2Fhearth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34127342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acp","agent-runtime","claude-code","karpathy-llm-wiki","markdown","obsidian","personal-knowledge-base","second-brain"],"created_at":"2026-06-09T21:30:32.509Z","updated_at":"2026-06-09T21:30:35.014Z","avatar_url":"https://github.com/ggshr9.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hearth\n\n\u003e The agent-native vault governance layer.\n\u003e Any AI can participate in maintaining your markdown vault — but must respect permission, citation, review, and audit rules.\n\n**Status**: v0.4 complete (alpha). [PRODUCT.md](./docs/PRODUCT.md) is the doctrine; [SPEC v0.4](./docs/SPEC.md) is the contract. v0.1 deterministic kernel + v0.3 channel runtime + adopt + v0.4 MCP server (agent instruction pack, token-gated apply, audit log) all shipped. See [INTEGRATIONS.md](./docs/INTEGRATIONS.md) to mount hearth in Claude Code / Cursor / Codex / Continue.dev. Next: v0.2 pending diff + v0.5 auto-policy.\n\n🔗 [tendhearth.com](https://tendhearth.com) — landing\n\n`hearth` is a personal AI runtime for your plain-markdown vault. It implements [Andrej Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — sources go in, an agent compiles them into a structured wiki, queries return citation-grounded answers, periodic lint keeps the wiki clean.\n\n## What makes hearth different\n\nYou already talk to ChatGPT, Claude, and Gemini in the same week. Their conversations don't land anywhere; cross-vendor continuity is broken; the rest of what you read / watch / record lives in three more silos. **hearth is the substrate that catches all of it — vendor-neutral, locally-owned, governed.**\n\nFour properties that come together:\n\n- **Vendor-neutral by construction.** Vault is plain markdown on your disk. Any AI talks to it through MCP — Claude, Codex, Cursor, future ones. No vendor rents your knowledge.\n- **Channel-first capture.** Everything you produce/consume lands here — chat conversations, articles, videos, voice — through the surfaces you already use (phone share sheet, WeChat, browser extension), not where you wish you were (sitting at your desk).\n- **Transaction-controlled writes.** The agent never writes the vault directly. It produces a `ChangePlan`; a vault kernel applies it after permission and policy checks. Run hearth for a week and never find a wiki page you didn't approve.\n- **Claim-level citations.** Every assertion in an agent-written page anchors to a specific source location — file + line, page number for PDFs, timestamp for video. \"Cite the file\" isn't enough; you cite the line.\n\nPlus a hard rule that makes the rest hold: **source-as-data, never instruction**. Ingested content (web pages, PDFs, chat transcripts) is treated as untrusted data — a malicious blog post can't hijack the agent.\n\n## Three verbs\n\n```\nIngest   →  new source enters → agent produces a ChangePlan; pending review queue\nQuery    →  ask in chat / voice → answer with claim-level citations\nLint     →  periodic audit → contradictions, orphans, drift, single-source claims\n```\n\n## Two-minute setup\n\n```bash\ngit clone https://github.com/ggshr9/hearth.git ~/Documents/hearth\ncd ~/Documents/hearth \u0026\u0026 bun install\n\n# One command. Detects your Obsidian vault, runs adopt with preview,\n# verifies with doctor, optionally writes a Claude Code MCP config.\nbun src/cli/index.ts setup\n```\n\nAfter setup, capture from anywhere:\n\n```bash\nhearth channel ingest --channel cli --message-id m1 --from you \\\n  --text \"your first thought\" --vault /path/to/vault\nhearth pending list\nhearth pending apply \u003cchange_id\u003e --vault /path/to/vault\nhearth query \"first thought\" --vault /path/to/vault\nhearth log --vault /path/to/vault --since 1d\n```\n\nOr, with Claude Code mounted via MCP (setup wizard offers to wire this for you):\n\n\u003e \"Read hearth://agent-instructions then hearth://schema, then propose a\n\u003e ChangePlan for this content: ...\"\n\nClaude Code uses the hearth tools directly; every mutation still goes through\nChangePlan + token gate + audit log.\n\nExpected output:\n\n- 1 `source-summary` page\n- ~6 `concept` pages\n- 1 MOC update\n- 1 citation-grounded answer (every claim anchored to a source line)\n- 1 lint report (likely \"no issues\" on a single-source vault)\n\n## What hearth is\n\nA runtime, not a UI. Obsidian — or Logseq, Foam, plain text — stays your editor. `hearth` is the agent that lives between your channels and your vault, always-on but never in the way.\n\n- **Channel-agnostic** — WeChat first via [`wechat-cc`](https://github.com/ggshr9/wechat-cc); telegram and voice next\n- **Agent-runtime-flexible** — currently runs on the Anthropic Claude Agent SDK; architecturally pluggable for ACP-compatible runtimes (Codex, OpenCode, future entrants)\n- **Editor-agnostic** — your vault is plain markdown, no lock-in\n\n## What hearth is NOT\n\n- Not another note-taking app (use Obsidian / Logseq / Foam)\n- Not a chatbot framework (see [OpenClaw](https://github.com/SamurAIGPT/awesome-openclaw))\n- Not an OS or a database — files on disk, plain text, no lock-in\n- Not a vendor-managed service (open source, self-hosted; optional hosted services may exist later)\n\n## How it differs from neighbors\n\n| neighbor | what they do | how hearth differs |\n|---|---|---|\n| [SamurAIGPT/llm-wiki-agent](https://github.com/SamurAIGPT/llm-wiki-agent) | Karpathy LLM Wiki via Claude Code | hearth adds chat/voice channels + transaction-controlled writes + claim-level citations |\n| [NicholasSpisak/second-brain](https://github.com/NicholasSpisak/second-brain) | Karpathy LLM Wiki for Obsidian | same pattern, but desktop-only; hearth is multi-channel runtime |\n| [obsidian-mcp-server](https://github.com/cyanheads/obsidian-mcp-server) | MCP server exposing vault CRUD | hearth includes Ingest/Query/Lint pipelines + the trust mechanisms — not just CRUD tools |\n| [obsidian-copilot](https://github.com/logancyang/obsidian-copilot) | in-vault AI assistant (Obsidian plugin) | hearth is a runtime, not a plugin — works without Obsidian running |\n| [OpenClaw](https://github.com/SamurAIGPT/awesome-openclaw) | multi-channel bot framework | complementary; hearth focuses on vault as substrate; planning to reuse OpenClaw channel adapters |\n| [memex-lab/memex](https://github.com/memex-lab/memex) | Flutter PKM with multi-agent capture | hearth is plain-md filesystem (no app), runtime not application |\n\n## Architecture (sketch)\n\n```\nChannels (consumable, swappable)\n  wechat-cc | telegram-cc | voice-app | cli | email | ...\n                ↓ (InboundMsg)        ↑ (Delivery)\n       ┌─────────── hearth ───────────┐\n       │  Ingest  →  ChangePlan       │\n       │  Query   →  Answer + claims  │\n       │  Lint    →  Report           │\n       │  Pending review queue        │\n       │  Cross-channel memory FS     │\n       │  Companion scheduler         │\n       └────┬───────────────┬─────────┘\n            │ Agent SDK     │ vault kernel (filesystem + SCHEMA.md perms)\n            ↓               ↓\n       Claude Agent     ~/vault/\n       SDK (or          raw/         (sources, append-only)\n       ACP-compat)      \u003ctopic\u003e/     (agent-maintained wiki)\n                        SCHEMA.md    (human-governed)\n```\n\n## Documentation\n\n- [`docs/PRODUCT.md`](./docs/PRODUCT.md) — **product compass** (positioning, principles, what hearth is and isn't)\n- [`docs/SPEC.md`](./docs/SPEC.md) — public contract: verbs, interfaces, scope discipline\n- [`docs/ROADMAP.md`](./docs/ROADMAP.md) — version path (trust closure first, format coverage last)\n- [`docs/SECURITY.md`](./docs/SECURITY.md) — threat model + the three trust pillars\n- [`docs/why.md`](./docs/why.md) — pattern background + design discipline\n- [`docs/INTEGRATIONS.md`](./docs/INTEGRATIONS.md) — copy-paste MCP config for Claude Code / Cursor / Codex / Continue.dev\n- [`docs/RESEARCH-AGENT.md`](./docs/RESEARCH-AGENT.md) — design note for proactive long-running research agents (Path 1 today, `hearth watch` later)\n\n## Status\n\n- [x] Naming + initial repo\n- [x] Landing ([tendhearth.com](https://tendhearth.com))\n- [x] **Foundations** — naming, landing ([tendhearth.com](https://tendhearth.com)), [PRODUCT](./docs/PRODUCT.md) / [SPEC](./docs/SPEC.md) / [ROADMAP](./docs/ROADMAP.md) / [SECURITY](./docs/SECURITY.md)\n- [x] **v0.1 — deterministic kernel** (init, ChangePlan transactions, claim-grounded query, lint, AgentAdapter w/ mock + Claude)\n- [x] **v0.3.0 — channel adapter spike** + adopt + doctor (`hearth setup` wizard one-command onboarding)\n- [x] **v0.4 — Agent Interface \u0026 Audit** (MCP server, agent instruction pack, token-gated apply, audit log, `hearth log`, [INTEGRATIONS](./docs/INTEGRATIONS.md) guide)\n- [ ] **v0.2 — pending review + diff + rebase**\n- [ ] **v0.3.1 / v0.3.2 — owner-only `/hearth` over WeChat + end-to-end mobile demo**\n- [ ] **v0.5 — auto-policy + risk classifier + audit rotation**\n- [ ] **v0.6 — Views before Moves + `hearth watch`** (see [RESEARCH-AGENT.md](./docs/RESEARCH-AGENT.md))\n- [ ] **v0.7 — human trust surface** (local console + multi-vault)\n- [ ] **Beyond v0.7** — voice capture, multi-format extractors, semantic search (see [ROADMAP](./docs/ROADMAP.md#beyond-v07))\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fggshr9%2Fhearth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fggshr9%2Fhearth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fggshr9%2Fhearth/lists"}