ottosulin/hwiki

hwiki: a markdown wiki as Hermes Agent memory

Long-term memory you can browse and edit easily. hwiki turns a folder of markdown files into Hermes Agent memory. The agent recalls from it before every turn and files new facts into it. You read, edit and reorganise the same files in editors and tools like Obsidian, and track every change in git.

The idea and structure is based on Karpathy's LLM wiki.

No opaque databases you can't easily browse, no cloud service, no extra dependencies: Python's standard library and a local SQLite FTS5 index.

You think querying the markdown memory is slow? The provider answers in milliseconds.

Why hwiki

Work on the same knowledge base as your agent

The wiki is a shared artifact, and you and the agent are co-authors:

• You curate in your favourite editor. Write pages, link them, restructure folders. hwiki re-indexes changes automatically, so the agent sees your edits within a minute.
• The agent recalls what you wrote. Before each turn the most relevant heading-sized excerpts are injected, with page and section, so answers are grounded in your notes and citable.
• The agent writes to a staging area, never over your pages. New facts are stored as dated bullets in wiki/memory/. You review them in your favourite markdown editor, promote what matters into proper pages, and delete the rest. One git diff shows everything the agent added.
• The graph works for both of you. [[wikilinks]] and backlinks render in tools like Obsidian's graph view and let the agent follow links instead of re-searching.

Install

hermes plugins install https://github.com/ottosulin/hwiki
hermes memory setup            # choose "hwiki", point it at your wiki folder
hermes gateway restart         # or restart the CLI
hermes hwiki status            # verify: root, backend, page count

Or configure it non-interactively:

hermes config set memory.provider hwiki
cat > ~/.hermes/hwiki.json <<'JSON'
{ "wiki_path": "~/wiki" }
JSON

Any folder of markdown works, including for example an existing Obsidian vault.

How it works

my-wiki/
├── wiki/              indexed and recalled, human-curated
│   ├── concepts/ ...
│   └── memory/        the ONLY place the agent writes (dated bullets)
└── raw/               never indexed, never recalled, never readable by memory tools

• Recall: heading-scoped chunks from SQLite FTS5 (BM25). Sub-10 ms on a 2,000-page wiki. Optional qmd hybrid semantic search, with automatic fallback to FTS5 if qmd is missing or slow.
• Writes: append-only to memory_dir, de-duplicated, with a secret guard that refuses API keys, tokens and private keys.
• Untrusted sources: put third-party documents in raw/. They never reach auto-injected context, which is where prompt-injection attacks are most dangerous. Summarise them into wiki/ yourself.
• Background agents are read-only: in cron, subagent and flush contexts the write tool is not offered, so automated runs cannot pollute your wiki.

About agent's access to the wiki

The write tool is intentionally simple, and currently there is no replace tool. Replace tool is something to be considered later. This restricted set of tools now intentional to support cases where you do not want to give the agent unrestricted access to the wiki files.

In practice in many use cases the agent should have access (running on same filesystem or wiki directory is mounted to the sandbox container) to the wiki files. This is the way I use this. By giving the agent also unrestricted access gives it most freedom to keep wiki pages up to date, save multiple documents from research etc. Plugin tool interfaces will always have friction compared to agent being able to use grep, sed and other command line tools. However, the search tool will outperform grep when amount of pages grows for recall, and also prevents polluting the results with hits from saved raw materials.

Agent tools

CLI

hermes hwiki status              # root, backend, counts
hermes hwiki search "release process"
hermes hwiki index               # force a full reindex
hermes hwiki lint                # dangling wikilinks, orphan pages
hermes hwiki config              # resolved configuration
hermes hwiki migrate --dry-run   # import facts from the holographic provider

Configuration

$HERMES_HOME/hwiki.json. Only wiki_path is required.

Environment overrides: HWIKI_PATH, HWIKI_BACKEND, HWIKI_MEMORY_DIR, HWIKI_QMD_BINARY, HWIKI_QMD_MODE. All options, qmd tuning and Docker setup: docs/configuration.md.

Privacy and security

• No network access with the default fts5 backend. Your notes never leave the machine. The optional qmd backend runs local models.
• Data locations: your wiki folder (which you choose) plus $HERMES_HOME/hwiki.json and $HERMES_HOME/hwiki-index.sqlite (disposable, rebuilt on demand).
• Writes are confined to memory_dir, path traversal is rejected, and search input is treated as data, never as query syntax.

Details: docs/security.md. Design rationale and benchmarks: docs/design.md.

Development

python3 tests/test_store_search.py   # store, chunking, search, trust boundary
python3 tests/test_provider.py       # full MemoryProvider contract
python3 tests/test_cli_load.py       # CLI loaded exactly as Hermes loads it
python3 -m pytest tests/             # naming, resolution (needs pytest + PyYAML)
hermes plugins validate .            # Hermes catalog admission checks

Contributions welcome; see CONTRIBUTING.md.

License

MIT