hongzhao

A file-based, human-gated memory ledger for AI coding agents.

Agents take notes constantly; most of those notes rot in chat logs. hongzhao gives your agent a small set of plain-text ledgers — claims, project contracts, knowledge entries — with deterministic validation and compilation. Nothing enters an agent's context until you (or a rule you wrote) say so.

• Plain files, no lock-in. Markdown + YAML under one root. No server, no database, no cloud.
• Two gates. Raw notes are candidates; compile turns reviewed candidates into effective views. Candidates never leak into context.
• Deterministic core. Validation, compilation and rendering are pure scripts; only semantic judgment (what is a fact, what supersedes what) belongs to the agent.

Status: pre-release (v0.1). Interfaces may change before v0.1.0.

Install with your AI agent (one line)

Tell your coding agent (Claude Code, Codex CLI, ZCode, ...):

Read https://github.com/cmeng-CM/hongzhao/blob/main/docs/INSTALL.md and install hongzhao for me. My client is claude_code.

It will follow the agent install protocol and report a pass/fail table. Prefer typing yourself? Manual install is three commands.

Support matrix

With / without

60-second quickstart

pip install hongzhao            # or: uv tool install hongzhao
hongzhao init ~/my-memory --example
hongzhao --root ~/my-memory compile
hongzhao --root ~/my-memory validate

You now have a green demo kit: raw notes, a compiled index, and a rendered bootstrap. Explore ~/my-memory/compiled/ — every view is plain markdown.

Daily loop:

hongzhao --root ~/my-memory validate     # schema + containment checks
hongzhao --root ~/my-memory compile      # rebuild derived views
hongzhao --root ~/my-memory doctor       # client / blocks / output health

Agent installation block

Paste this into your agent client's instruction file (or let bridge-install manage the block for you — see docs/clients.md):

# hongzhao memory routing
memory_root: ~/my-memory
Read compiled/bootstrap.md first; route tasks via compiled/effective-memory/index.md.
Never read raw/ except for evidence tracing. Run `hongzhao --root ~/my-memory compile`
after writing records; treat compile errors as stop signals.

How it works

raw/ (claims, dated truth)        ──compile──▶  compiled/ (effective views)
registry/ + project contracts     ──compile──▶  render/   (bootstrap, client blocks)
knowledge registry                ──compile──▶  knowledge map

Five explicit relations between claims (supersedes, covers, derives, conflicts, resolves) replace "newest wins". See docs/claim-schema.md and the diagrams in docs/design.md.

Non-goals

• No MCP server, no vector search, no RAG, no auto-extraction, no web UI.
• No team sharing / multi-machine sync (single-writer by design).
• No Windows native support in v0.1.
• No background daemons — every command is explicit, every write is atomic.

Why-not

Approaches we deliberately did not take (and what to use instead):

• Vector DB / embeddings: file paths and titles already route a coding agent well; retrieval quality was not the bottleneck, review discipline was.
• Auto-summarization on every turn: unreviewed summaries are how memory rots; hongzhao makes candidates explicit and gates them.
• A server / API: a memory you cannot grep, diff, and back up with git is not your memory.
• An embedded database: merge conflicts and plain-text portability beat query power at this data scale.

Full documentation: docs/. Security model: SECURITY.md. Contributing (DCO required): CONTRIBUTING.md. Beta program: docs/beta.md.

License: Apache-2.0 — see LICENSE. 中文简介：README.zh-CN.md。