{"id":50645407,"url":"https://github.com/tjboudreaux/hermes-wiki","last_synced_at":"2026-06-07T12:01:59.411Z","repository":{"id":362833157,"uuid":"1260959762","full_name":"tjboudreaux/hermes-wiki","owner":"tjboudreaux","description":"Karpathy-style LLM Wikis for the Hermes Agent — persistent, compounding knowledge bases curated by AI agents","archived":false,"fork":false,"pushed_at":"2026-06-06T06:54:16.000Z","size":403,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T07:04:14.969Z","etag":null,"topics":["agent-tools","ai-agent","ai-memory","hermes","karpathy-pattern","knowledge-base","knowledge-management","llm-wiki","python","rag"],"latest_commit_sha":null,"homepage":"https://tjboudreaux.github.io/hermes-wiki","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tjboudreaux.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-06T04:23:45.000Z","updated_at":"2026-06-06T06:54:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tjboudreaux/hermes-wiki","commit_stats":null,"previous_names":["tjboudreaux/hermes-wiki"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tjboudreaux/hermes-wiki","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjboudreaux%2Fhermes-wiki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjboudreaux%2Fhermes-wiki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjboudreaux%2Fhermes-wiki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjboudreaux%2Fhermes-wiki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tjboudreaux","download_url":"https://codeload.github.com/tjboudreaux/hermes-wiki/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjboudreaux%2Fhermes-wiki/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34020187,"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-07T02:00:07.652Z","response_time":124,"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":["agent-tools","ai-agent","ai-memory","hermes","karpathy-pattern","knowledge-base","knowledge-management","llm-wiki","python","rag"],"created_at":"2026-06-07T12:01:58.331Z","updated_at":"2026-06-07T12:01:59.402Z","avatar_url":"https://github.com/tjboudreaux.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/hermes-wiki-banner.svg\" alt=\"Hermes Wiki — Karpathy-style LLM Wikis for the Hermes Agent\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eHermes Wiki\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eKarpathy-style LLM Wikis for Hermes — persistent, compounding knowledge bases that agents curate over time.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"https://hermes-wiki.github.io/hermes-wiki/\"\u003eDocumentation\u003c/a\u003e •\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e •\n  \u003ca href=\"#faq\"\u003eFAQ\u003c/a\u003e •\n  \u003ca href=\"CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/hermes-wiki/hermes-wiki/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/hermes-wiki/hermes-wiki/ci.yml?branch=main\u0026style=flat-square\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/hermes-wiki/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/hermes-wiki?style=flat-square\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/hermes-wiki/hermes-wiki/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/hermes-wiki/hermes-wiki?style=flat-square\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/pypi/pyversions/hermes-wiki?style=flat-square\" alt=\"Python 3.11+\"\u003e\n\u003c/p\u003e\n\n---\n\n## What is Hermes Wiki?\n\nHermes Wiki is a Python package that gives AI agents persistent, compounding knowledge bases instead of traditional RAG. It implements [Andrej Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) for the [Hermes Agent](https://github.com/nous-research/hermes): agents ingest sources, synthesize interlinked wiki pages, and maintain knowledge over time — so they never rediscover context from scratch.\n\n```\n┌─────────────────────────────────────────────────────────┐\n│  Raw Sources (Immutable)                                │\n│  Articles, papers, transcripts — agents read, never     │\n│  modify. Append-only with sha256 provenance.            │\n└────────────────────────┬────────────────────────────────┘\n                         │ ingest\n                         ▼\n┌─────────────────────────────────────────────────────────┐\n│  LLM Wiki (Agent-Maintained)                            │\n│  Entity pages, concept pages, comparisons, summaries.   │\n│  Cross-referenced, attributed, git-committed.           │\n└────────────────────────┬────────────────────────────────┘\n                         │ query / lint / monitor\n                         ▼\n┌─────────────────────────────────────────────────────────┐\n│  Surfaces: CLI + Agent Tools + Dashboard                │\n│  hermes-wiki CLI, /wiki slash commands, React dashboard │\n└─────────────────────────────────────────────────────────┘\n```\n\n### The Karpathy Pattern, Implemented\n\nKarpathy's insight: LLMs should **curate**, not just retrieve. Traditional RAG uploads documents and retrieves chunks at query time. The LLM Wiki pattern instead has agents:\n\n1. **Ingest** sources into structured wiki pages with cross-references\n2. **Maintain** pages over time — resolve contradictions, update stale claims, link new evidence\n3. **Compound** knowledge — each ingestion enriches the whole wiki, not just one answer\n\nHermes Wiki makes this operational with a CLI, agent tools, and a web dashboard.\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **CLI** | Full `hermes-wiki` command surface: create, ingest, search, lint, link, monitor |\n| **Agent Tools** | `wiki_search`, `wiki_show`, `wiki_ingest`, `wiki_create_page` — agents use wikis in conversation |\n| **Dashboard** | React 19 plugin tab in the Hermes dashboard with search, inbox, health, and activity views |\n| **Attribution** | Every change is attributed (agent/profile/human/cron) with triple redundancy: frontmatter + SQLite + git |\n| **Privacy** | Profile-scoped visibility with whitelist/blacklist — invisible wikis never leak their names |\n| **Health \u0026 Lint** | 19 automated checks: broken links, orphans, stale content, projection drift, untrusted plugins |\n| **Kanban Linkage** | Bidirectional wiki-page ↔ kanban-task references (wiki-owned, read-only to kanban) |\n| **Pluggable Pipeline** | Custom classifiers and processors per wiki, with explicit trust-before-execute security |\n| **Git-Backed** | Each wiki is its own git repository; projection DBs are rebuildable from markdown |\n\n## Installation\n\n### Requirements\n\n- Python 3.11+ and [uv](https://docs.astral.sh/uv/)\n- Node.js + npm (dashboard only)\n- An [OpenRouter API key](https://openrouter.ai/) for LLM-backed features\n\n### Install\n\n```bash\ngit clone https://github.com/hermes-wiki/hermes-wiki.git\ncd hermes-wiki\nuv sync\n```\n\n### Verify\n\n```bash\nuv run hermes-wiki --help\n```\n\n## Quick Start\n\n```bash\n# 1. Create a wiki\nuv run hermes-wiki create ai-tooling --domain \"AI agents and coding tools\"\n\n# 2. Ingest a source\nuv run hermes-wiki ingest https://example.com/transformer-paper --wiki ai-tooling\n\n# 3. Search the wiki\nuv run hermes-wiki search \"attention mechanism\" --wiki ai-tooling\n\n# 4. Check health\nuv run hermes-wiki lint --wiki ai-tooling\n```\n\n### With an Isolated Home (Recommended for Development)\n\n```bash\n# Seed an isolated Hermes home at .hermes-test\nuv run python -m hermes_wiki.harness --repo-root \"$(pwd)\" init\nexport HERMES_HOME=\"$(pwd)/.hermes-test\"\n\n# Start the dashboard\nuv run python -m hermes_wiki.harness --repo-root \"$(pwd)\" dashboard start --port 9123\n# Open http://127.0.0.1:9123 → Wikis tab\n```\n\n## Architecture\n\n### Markdown is Authoritative\n\nWiki pages are plain `.md` files with YAML frontmatter. SQLite (`wiki.db`) is a **rebuildable projection** — if it disagrees with the markdown files, the files win and the projection is rebuilt.\n\n```yaml\n---\nid: concepts/attention-mechanism\ntitle: Attention Mechanism\ntype: concept\ntags: [transformers, nlp, attention]\nsources: [raw/papers/vaswani-2017.pdf]\nconfidence: high\nauthor: claude-opus-4.8\nauthor_kind: agent\n---\n\n# Attention Mechanism\n...\n```\n\n### Storage Layer\n\n```\n~/.hermes/wikis/\u003cslug\u003e/\n├── .git/              # Per-wiki git repository\n├── wiki.db            # Rebuildable FTS5 projection (gitignored)\n├── SCHEMA.md          # Domain contract, taxonomy, update policy\n├── index.md           # Page catalog\n├── log.md             # Attributed action log\n├── raw/\n│   ├── inbox/         # Drop zone for unprocessed sources\n│   ├── articles/\n│   └── papers/\n├── entities/          # Entity pages\n├── concepts/          # Concept pages\n├── comparisons/       # Comparison pages\n└── sources/           # Curated source summary pages\n```\n\n### Processing Pipeline\n\n```\nraw/inbox/ → [Classifier] → label → [Processor] → Wiki Pages → [Propagator] → git commit\n                                                                      ↓\n                                                              wiki.db + index.md + log.md\n```\n\nBuilt-in classifiers: `article`, `paper`, `transcript`, `image`, `audio`, `code-snippet`.\nCustom classifiers/processors require explicit trust (`hermes-wiki plugins trust`).\n\n### Adapter Architecture\n\nThe package is **standalone-first** with typed Protocol seams:\n\n| Adapter | Use Case |\n|---------|----------|\n| `adapters/standalone/` | Default — runs without Hermes installed |\n| `adapters/hermes/` | Wires into a real Hermes deployment (CLI registration, cron, prompt injection) |\n\n## CLI Reference\n\n```bash\n# Wiki management\nhermes-wiki create \u003cslug\u003e              # Create a new wiki\nhermes-wiki list                       # List visible wikis\nhermes-wiki show \u003cslug\u003e                # Wiki summary and stats\nhermes-wiki switch \u003cslug\u003e              # Set as current wiki for this profile\nhermes-wiki archive \u003cslug\u003e             # Hide from discovery (reversible)\n\n# Content\nhermes-wiki ingest \u003cpath|url\u003e          # Ingest a source\nhermes-wiki ingest --inbox             # Process all inbox items\nhermes-wiki search \u003cquery\u003e             # BM25 full-text search\nhermes-wiki open \u003cpage-id\u003e             # Read a page\nhermes-wiki create-page \u003ctitle\u003e        # Author a new page\nhermes-wiki list-pages                 # List pages (filterable)\n\n# Maintenance\nhermes-wiki lint                       # Run health checks\nhermes-wiki log                        # View activity log\nhermes-wiki plugins list               # Show classifiers/processors\n\n# Kanban integration\nhermes-wiki link \u003cpage-id\u003e \u003ctask-id\u003e   # Link page to kanban task\nhermes-wiki refs \u003cpage-id\u003e             # Show linked tasks\n```\n\nSee `hermes-wiki \u003ccommand\u003e --help` for full options.\n\n## Agent Tools\n\nWhen running inside Hermes, agents discover wikis via system prompt injection and use typed tools:\n\n| Tool | Access | Description |\n|------|--------|-------------|\n| `wiki_list` | Read | List visible wikis or pages |\n| `wiki_search` | Read | FTS5 search across visible wikis |\n| `wiki_show` | Read | Full page content with metadata |\n| `wiki_health_check` | Read | Lint report |\n| `wiki_inbox` | Read | Unprocessed inbox items |\n| `wiki_ingest` | Write | Run ingest pipeline |\n| `wiki_create_page` | Write | Create/update a page |\n| `wiki_link_kanban` | Write | Link page to kanban task |\n\nWrite tools require a write grant (profile config, `HERMES_WIKI` env, or `wiki` toolset).\n\n## Dashboard\n\nThe dashboard is a React 19 plugin tab (`/wikis`) inside the Hermes dashboard, built with `@nous-research/ui`.\n\n**Views:** Wiki Landing | Wiki Detail | Page View | Search | Inbox | Health | Activity Log\n\n**Backend:** FastAPI router at `/api/plugins/wiki/*` with session-token auth.\n\n```bash\n# Build and run\ncd dashboard \u0026\u0026 npm install \u0026\u0026 npm run build \u0026\u0026 cd ..\nuv run python -m hermes_wiki.harness --repo-root \"$(pwd)\" dashboard start --port 9123\n```\n\n## How This Implements Karpathy's LLM Wiki\n\n| Karpathy Concept | Hermes Wiki Implementation |\n|------------------|---------------------------|\n| Raw sources (immutable) | `raw/` directory with append-only snapshots, sha256 provenance |\n| LLM-maintained wiki pages | `entities/`, `concepts/`, `comparisons/`, `sources/` — agent-curated markdown |\n| Schema / CLAUDE.md | `SCHEMA.md` per wiki — domain contract, taxonomy, propagation rules |\n| Index | `index.md` — sectioned page catalog |\n| Log | `log.md` — append-only attributed action record |\n| Ingest operation | `hermes-wiki ingest` — classifies, processes, cross-links, commits |\n| Query operation | `hermes-wiki search` / `wiki_search` tool — BM25 FTS5 ranked |\n| Lint operation | `hermes-wiki lint` — 19 health checks for contradictions, staleness, orphans |\n| Knowledge compounds | Each ingest updates related pages, not just the new source's page |\n| Human curates sources, LLM does the rest | Agents ingest, synthesize, cross-link; humans drop sources in inbox |\n\n## Development\n\n```bash\nuv run pytest              # Run tests\nuv run ruff check .        # Lint\nuv run ty check            # Type check (pinned to 0.0.44)\ncd dashboard \u0026\u0026 npm run build   # Build dashboard\n```\n\n## Project Layout\n\n```\nhermes_wiki/        Core: ingest pipeline, projection, search, lint, attribution, tools, harness\nhermes_wiki_cli/    Console entrypoint (argument parsing + dispatch)\nadapters/           Protocol seams: standalone (default) and hermes implementations\ndashboard/          React 19 plugin: src/, dist/, manifest.json, plugin_api.py\nfixtures/           Test data factory and seed sources\ntests/              Behavioral test suite\n```\n\n## Why Hermes Wiki?\n\n- **Knowledge compounds** — each ingestion enriches the entire wiki, not just one answer\n- **Markdown is authoritative** — no vendor lock-in; SQLite is a rebuildable projection\n- **Full attribution** — every change tracked to agent, profile, human, or cron job\n- **Privacy by default** — invisible wikis never leak their names\n- **Standalone-first** — runs without Hermes installed; adapters wire into real deployments\n- **19 health checks** — automated lint catches broken links, stale content, orphan pages\n\n## FAQ\n\n### What is an LLM Wiki?\n\nAn LLM Wiki is a domain-scoped knowledge base where AI agents compile, cross-reference, and maintain durable knowledge from human-curated sources. Unlike traditional RAG (which retrieves document chunks at query time), an LLM Wiki has agents incrementally build structured, interlinked pages that persist and compound over time.\n\n### How does Hermes Wiki differ from RAG?\n\nRAG retrieves document chunks at query time — the LLM rediscovers knowledge from scratch on every question. Hermes Wiki instead has agents ingest sources into structured wiki pages with cross-references, contradictions flagged, and provenance tracked. Knowledge accumulates rather than being forgotten between sessions.\n\n### What is the Karpathy Pattern?\n\nThe Karpathy Pattern refers to [Andrej Karpathy's LLM Wiki concept](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): immutable raw sources are ingested by an LLM into agent-curated, interlinked wiki pages governed by a schema, index, and log. The human curates sources and asks questions; the LLM handles synthesis, cross-referencing, and maintenance.\n\n### Do I need Hermes installed to use this?\n\nNo. Hermes Wiki is standalone-first. The `hermes-wiki` CLI works independently. The `adapters/hermes/` layer wires it into a full Hermes deployment when available, enabling agent tools, slash commands, and dashboard integration.\n\n### What storage does Hermes Wiki use?\n\nMarkdown files with YAML frontmatter are the source of truth. Each wiki has its own git repository. A SQLite database with FTS5 provides full-text search, but it is a rebuildable projection — if markdown and SQLite disagree, the files win.\n\n### How does the ingest pipeline work?\n\nSources are classified (article, paper, transcript, etc.), processed into one or more wiki pages, propagated to update cross-references and the index, then committed to git with full attribution. Custom classifiers and processors can be added per-wiki with explicit trust gating.\n\n### Can multiple agents share a wiki?\n\nYes. Wikis are profile-scoped with configurable visibility (whitelist/blacklist). Multiple agents can read and search any visible wiki. Write access requires explicit grants. Each agent's contributions are attributed separately.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and PR guidelines.\n\n## License\n\n[MIT](LICENSE) — Hermes Wiki contributors\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eImplements \u003ca href=\"https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f\"\u003eKarpathy's LLM Wiki pattern\u003c/a\u003e for the \u003ca href=\"https://github.com/nous-research/hermes\"\u003eHermes Agent\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftjboudreaux%2Fhermes-wiki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftjboudreaux%2Fhermes-wiki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftjboudreaux%2Fhermes-wiki/lists"}