# memhtml

> Memory for agents, in HTML.

memhtml stores an agent's long-term memory as a git repository of semantic HTML5 files,
one fact per file, with a rebuildable SQLite index over the tree. Two surfaces reach the
same store: the `memhtml` CLI and an MCP server over stdio.

Start here:

- [For agents](https://memhtml.github.io/agents.md): what to read first, whether you are behind the CLI or the MCP server, and the shortest path to a working integration.

Every page on this site is also served as Markdown at its own path with `.md` appended.
Fetch that rather than the rendered HTML.

## Documentation Sets

- [Abridged documentation](https://memhtml.github.io/llms-small.txt): a compact version of the documentation for memhtml, with non-essential content removed
- [Complete documentation](https://memhtml.github.io/llms-full.txt): the full documentation for memhtml

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Pages

Every page, as the Markdown an agent should fetch. The landing page and the agent page first,
then each tier in the order the site's navigation uses.

- [memhtml](https://memhtml.github.io/.md): An agent's long-term memory as a git repository of semantic HTML files, with a rebuildable SQLite index, retrieval that fuses four ranking arms, and a seventeen-phase curation pass.
- [For agents](https://memhtml.github.io/agents.md): What to unlearn, which surface you are on, and the shortest path from nothing to a working memhtml integration.
- [Learn](https://memhtml.github.io/learn.md): Tutorials that take you from a clone to a working memory store, and how-to pages for operating one.
- [Audit and publish the corpus](https://memhtml.github.io/learn/operations/audit-and-publish-the-corpus.md): Every memhtml doctor finding and its fix, what --fix will and will not repair, and how memhtml publish resolves a conflict in a generated file.
- [Check the discrimination gate](https://memhtml.github.io/learn/operations/check-the-discrimination-gate.md): Run the gate, read its report, and tell a skipped run from a passing one.
- [Configure the environment](https://memhtml.github.io/learn/operations/configure-the-environment.md): The environment variables memhtml reads, what each one degrades when it is absent, how to route model calls through an LLM proxy, and the SQLite settings every connection applies.
- [Diagnose poor retrieval](https://memhtml.github.io/learn/operations/diagnose-poor-retrieval.md): Where to look when search returns the wrong thing, nothing errors, and the store looks fine, plus the full error-code table.
- [Hooks and recall](https://memhtml.github.io/learn/operations/hooks-and-recall.md): What each installed hook injects on each host, why a hook that fails prints nothing, the time bounds it runs under, and how to run one by hand to see exactly what a host sees.
- [Index session transcripts](https://memhtml.github.io/learn/operations/index-session-transcripts.md): Scan Claude Code transcripts into the trace plane, search them, join them to memories, and understand the firewall between traces and memory retrieval.
- [Initialize a store](https://memhtml.github.io/learn/operations/initialize-a-store.md): Scaffold a memory repository, and why a fresh clone must run memhtml init before its first merge touches a generated file.
- [Preserve the state plane](https://memhtml.github.io/learn/operations/preserve-the-state-plane.md): Export and import the access plane, the one set of facts the git tree cannot reproduce, and handle the hazard it carries across two machines.
- [Rebuild the index](https://memhtml.github.io/learn/operations/rebuild-the-index.md): When update is enough, when only a full rebuild will do, and how to clear a vector-space mismatch that a rebuild alone cannot.
- [Recover from a lost index](https://memhtml.github.io/learn/operations/recover-from-a-lost-index.md): Restore a store from a clone in four commands, in the order that matters, and know exactly what a rebuild cannot bring back.
- [Run and review a sleep cycle](https://memhtml.github.io/learn/operations/run-and-review-a-sleep-cycle.md): Seventeen curation phases on a review branch: how to run them, how to read the diff, what a failed phase costs, and why a merge refuses.
- [Run the store day to day](https://memhtml.github.io/learn/operations/run-the-store-day-to-day.md): The daily verbs, the cron schedule that keeps a store fresh, and exactly what moves the access plane.
- [Share one store between a CLI and a server](https://memhtml.github.io/learn/operations/share-one-store.md): Why a memhtml command and a running MCP server can touch one database at once, what the retry layer guarantees, and the one operation that still needs exclusivity.
- [Wire up your coding agent](https://memhtml.github.io/learn/operations/wire-a-coding-agent.md): What memhtml integrations install writes for Claude Code, Codex, Cursor, and OpenCode, which step each host still needs from you, and how uninstall removes exactly what install wrote.
- [Write your first memory](https://memhtml.github.io/learn/tutorial/first-memory.md): Run memhtml write, read the file it commits into the git tree, and see why one fact goes in one file.
- [Retrieve it](https://memhtml.github.io/learn/tutorial/first-retrieval.md): Run memhtml search and memhtml recall against the memory you wrote, and learn what separates the two.
- [Install memhtml and initialize a store](https://memhtml.github.io/learn/tutorial/install.md): Install the memhtml package, or build it from a clone, then scaffold a git-initialized memory store.
- [Wire up the MCP server](https://memhtml.github.io/learn/tutorial/mcp-server.md): Run memhtml serve mcp over stdio, see the tools and resources a client gets, and call one by hand.
- [Reference](https://memhtml.github.io/reference.md): Every command, code, vocabulary, and requirement, read from the source that defines it.
- [memhtml agents-doc](https://memhtml.github.io/reference/commands/agents-doc.md): Regenerate AGENTS.md from this command table. --check fails on drift.
- [memhtml apply](https://memhtml.github.io/reference/commands/apply.md): Write many memories from a JSONL op stream: ONE commit, ONE index update, per-op results.
- [memhtml archive](https://memhtml.github.io/reference/commands/archive.md): Soft-evict: `git mv` into archive/<YYYY>/ with the archive stamps. Never a delete.
- [memhtml correct](https://memhtml.github.io/reference/commands/correct.md): Supersede a memory: write the new file and archive the target in ONE commit.
- [memhtml doctor](https://memhtml.github.io/reference/commands/doctor.md): Corpus health: dangling hrefs, orphan state rows, inbox depth, vocabulary, staleness.
- [memhtml entity activity](https://memhtml.github.io/reference/commands/entity-activity.md): Every entity with its file count and its last activity, newest first. Report only.
- [memhtml eval discriminate](https://memhtml.github.io/reference/commands/eval-discriminate.md): The refusable retrieval gate: every probe must outrank its own wrong-fact twins.
- [memhtml exec](https://memhtml.github.io/reference/commands/exec.md): Run a read-only traversal script over the corpus in a sandbox: multi-hop in ONE execution.
- [memhtml help](https://memhtml.github.io/reference/commands/help.md): Describe one command: usage, arguments, flags, response type, examples. Markdown on a terminal, a cli.help envelope when piped.
- [memhtml hook](https://memhtml.github.io/reference/commands/hook.md): The engine every installed hook calls. Reads the host's hook payload on stdin, runs recall or transcript indexing under a hard time bound, and writes the HOST'S protocol to stdout (plain text or the host's JSON), never this envelope; any failure prints nothing and exits 0, so a hook can never block a turn.
- [memhtml index embed](https://memhtml.github.io/reference/commands/index-embed.md): Fill every chunk that has no vector in the configured space, without a rebuild. Safe to rerun; reports the gap it left.
- [memhtml index rebuild](https://memhtml.github.io/reference/commands/index-rebuild.md): Rebuild index.db from the git tree at HEAD, keeping every stored vector whose chunk survives. Destroys nothing outside .memhtml/.
- [memhtml index status](https://memhtml.github.io/reference/commands/index-status.md): The index watermark, the vector space it was built in, and its row counts.
- [memhtml index update](https://memhtml.github.io/reference/commands/index-update.md): Index only what moved since the recorded watermark, plus the dirty working tree.
- [memhtml init](https://memhtml.github.io/reference/commands/init.md): Scaffold a memory repo at --repo/$MEMHTML_ROOT: git init, PARA dirs, merge driver.
- [memhtml integrations doctor](https://memhtml.github.io/reference/commands/integrations-doctor.md): Check a host's wiring end to end: binary path and version, store root, MCP entry, hooks, instruction block, skill, transcript root, and a live `initialize` handshake with the server the entry names.
- [memhtml integrations install](https://memhtml.github.io/reference/commands/integrations-install.md): Wire a coding agent to this store: its MCP entry, its hooks, a fenced block in its instruction file, and a skill, recorded in a receipt so uninstall removes exactly what install wrote.
- [memhtml integrations list](https://memhtml.github.io/reference/commands/integrations-list.md): For every host: installed, modified, or not installed, at user scope and at the named project scope.
- [memhtml integrations shell](https://memhtml.github.io/reference/commands/integrations-shell.md): Print an eval-able shell snippet that exports MEMHTML_ROOT and puts this binary's directory on PATH; --write appends it to your rc file inside a fence.
- [memhtml integrations uninstall](https://memhtml.github.io/reference/commands/integrations-uninstall.md): Remove exactly what install wrote for one host, matched against the receipt; a managed file that was modified since is refused.
- [memhtml link](https://memhtml.github.io/reference/commands/link.md): Add an authored edge to the source file and commit it. Idempotent.
- [memhtml list](https://memhtml.github.io/reference/commands/list.md): Page through the corpus by type, workspace, tag, entity, facet, or PARA bucket.
- [memhtml manifest](https://memhtml.github.io/reference/commands/manifest.md): Emit this CLI's full machine-readable contract.
- [memhtml neighbors](https://memhtml.github.io/reference/commands/neighbors.md): The memory graph around one path, to a fixed depth of at most two hops.
- [memhtml publish](https://memhtml.github.io/reference/commands/publish.md): Regenerate the per-directory index.html listings and sitemap.xml, and commit them.
- [memhtml read](https://memhtml.github.io/reference/commands/read.md): Read one memory: its metas, links, article, and format warnings.
- [memhtml recall](https://memhtml.github.io/reference/commands/recall.md): A disclosure pack under a character budget: arcs and memories folded separately.
- [memhtml reinforce](https://memhtml.github.io/reference/commands/reinforce.md): Bump access bookkeeping, gated by a 900-second per-path cooldown.
- [memhtml resolve](https://memhtml.github.io/reference/commands/resolve.md): Follow a possibly-moved path forward to the memory that carries the fact now.
- [memhtml search](https://memhtml.github.io/reference/commands/search.md): Ranked search: four RRF arms plus MMR. Degrades to the lexical floor.
- [memhtml serve mcp](https://memhtml.github.io/reference/commands/serve-mcp.md): Run the `memhtml-mcp` stdio server: 15 tools and 3 resources over this same repo.
- [memhtml sleep merge](https://memhtml.github.io/reference/commands/sleep-merge.md): Fast-forward main to the run's branch after the discrimination gate passes, then project the merged commit into the index.
- [memhtml sleep plan](https://memhtml.github.io/reference/commands/sleep-plan.md): Would a run change anything? Read the signals from index counts, running no phase.
- [memhtml sleep resume](https://memhtml.github.io/reference/commands/sleep-resume.md): Re-run only the phases with no Memhtml-Phase trailer on the branch.
- [memhtml sleep review](https://memhtml.github.io/reference/commands/sleep-review.md): Per-phase counts, the commit list, diff --stat, and a per-file classification.
- [memhtml sleep run](https://memhtml.github.io/reference/commands/sleep-run.md): The curation cycle: 17 phases, each an isolated commit on a review branch.
- [memhtml sleep status](https://memhtml.github.io/reference/commands/sleep-status.md): The latest sleep run and its per-phase outcomes.
- [memhtml state export](https://memhtml.github.io/reference/commands/state-export.md): Write .memhtml/state/access.jsonl, the only durable copy of the state plane, and commit.
- [memhtml state import](https://memhtml.github.io/reference/commands/state-import.md): Replay the committed sidecar into state.db. Counters merge by max, never last-wins.
- [memhtml status](https://memhtml.github.io/reference/commands/status.md): Corpus health: HEAD, dirty state, counts by type, edges, index freshness.
- [memhtml task add](https://memhtml.github.io/reference/commands/task-add.md): Open a task: a `task` memory in projects/<ws>/tasks/ or areas/inbox/tasks/.
- [memhtml task list](https://memhtml.github.io/reference/commands/task-list.md): The task working set: a direct indexed scan with blockers, never ranked retrieval.
- [memhtml task status](https://memhtml.github.io/reference/commands/task-status.md): Move a task's status. `done` stamps AND archives it, in one commit.
- [memhtml trace index](https://memhtml.github.io/reference/commands/trace-index.md): Scan $MEMHTML_TRACE_ROOT for Claude Code transcripts, reading only what changed.
- [memhtml trace links](https://memhtml.github.io/reference/commands/trace-links.md): The memory-session links, from either side.
- [memhtml trace search](https://memhtml.github.io/reference/commands/trace-search.md): FTS over session first-prompts and AI titles. Never enters memory retrieval.
- [memhtml write](https://memhtml.github.io/reference/commands/write.md): Write one memory. Content-hash duplicates return the existing path, uncommitted.
- [Environment variables](https://memhtml.github.io/reference/config.md): Every variable the binary reads, and what it does when one is unset.
- [Contracts](https://memhtml.github.io/reference/contracts.md): Every symbol @memhtml/contracts exports, with the doc comment written beside it in the source.
- [The JSON envelope](https://memhtml.github.io/reference/envelope.md): One JSON envelope per command on stdout, with logs kept on stderr.
- [Error codes](https://memhtml.github.io/reference/error-codes.md): What a failure carries, and where each code comes from.
- [Global flags](https://memhtml.github.io/reference/global-flags.md): The flags every command accepts, whichever command it is.
- [The guide](https://memhtml.github.io/reference/guide.md): The workflow prose the CLI publishes on a first call, one page per topic.
- [authoring](https://memhtml.github.io/reference/guide/authoring.md): The authoring block of the CLI's guide.
- [code-mode](https://memhtml.github.io/reference/guide/code-mode.md): The code-mode block of the CLI's guide.
- [conflicts](https://memhtml.github.io/reference/guide/conflicts.md): The conflicts block of the CLI's guide.
- [first-call](https://memhtml.github.io/reference/guide/first-call.md): The first-call block of the CLI's guide.
- [recall-discipline](https://memhtml.github.io/reference/guide/recall-discipline.md): The recall-discipline block of the CLI's guide.
- [when-to-batch](https://memhtml.github.io/reference/guide/when-to-batch.md): The when-to-batch block of the CLI's guide.
- [write-surfaces](https://memhtml.github.io/reference/guide/write-surfaces.md): The write-surfaces block of the CLI's guide.
- [MCP resources](https://memhtml.github.io/reference/mcp-resources.md): What a client can fetch by URI: the file behind an answer, a sleep run's report, and a memory pinned at a commit.
- [MCP tools](https://memhtml.github.io/reference/mcp-tools.md): The tools the stdio server publishes, in the order a client receives them.
- [Packages](https://memhtml.github.io/reference/packages.md): Every workspace package, what it owns, and which siblings it imports.
- [Requirements](https://memhtml.github.io/reference/requirements.md): Every requirement in the ledger, its status, and the method that verifies it.
- [Response types](https://memhtml.github.io/reference/response-types.md): The `type` field a caller reads before it parses `data`.
- [RRF arms](https://memhtml.github.io/reference/rrf-arms.md): The ranking arms, their weights, and what each one needs before it can fire.
- [Database schema and migrations](https://memhtml.github.io/reference/schema.md): The two SQLite planes, and every migration that builds them.
- [Sleep phases](https://memhtml.github.io/reference/sleep-phases.md): The curation cycle's phases, in execution order.
- [Closed vocabularies](https://memhtml.github.io/reference/vocabulary.md): The fixed sets a value must come from: memory types, edge relations, PARA buckets, task statuses, and edge provenance.
- [Internals](https://memhtml.github.io/internals.md): Why the system is built the way it is, with the implementing code cited for every decision.
- [Concurrency and conflicts](https://memhtml.github.io/internals/concurrency-and-conflicts.md): Git supplies the concurrency control, a same-file collision comes back as a typed error carrying both shas, and a curation run is stricter than an agent write.
- [Edge encoding](https://memhtml.github.io/internals/edge-encoding.md): Authored edges live in the HTML, mined edges live only in the index, and four classes that never mix keep a to-do list out of the knowledge graph.
- [Four-arm retrieval](https://memhtml.github.io/internals/four-arm-retrieval.md): Four rankers folded into one SQL statement, weighted rank fusion, degradation as a filter, a diversification pass, and the disclosure fold.
- [The index plane and the state plane](https://memhtml.github.io/internals/index-plane-and-state-plane.md): What git cannot reproduce, why it is gitignored anyway, and the byte-stable committed sidecar that is its only durable copy.
- [Measured standing](https://memhtml.github.io/internals/measured-standing.md): The benchmark numbers this system has measured, with the caveat about judges that governs how to read them.
- [Packages and dependency direction](https://memhtml.github.io/internals/packages-and-dependency-direction.md): The layering, the test that enforces the pure packages' purity, the single place every service is wired together, and why fourteen packages ship as one.
- [Store layout and path algebra](https://memhtml.github.io/internals/store-layout-and-path-algebra.md): Four fixed top-level buckets, placement as a pure total function, and an archive mapping that can be inverted.
- [Testing posture](https://memhtml.github.io/internals/testing-posture.md): A real driver and a real git binary, fakes at the two network edges only, property tests over the pure packages, and a quality gate that refuses on one inversion.
- [The consolidator](https://memhtml.github.io/internals/the-consolidator.md): The live system prompt of the agent that distills candidate memories out of raw transcripts, reproduced as the artifact it is.
- [The envelope contract](https://memhtml.github.io/internals/the-envelope-contract.md): One JSON envelope per command, append-only response types and error codes, and a tool surface whose two hard constraints come from the transport rather than from taste.
- [The extension contract](https://memhtml.github.io/internals/the-extension-contract.md): Which axes a consumer may model its own domain on, which vocabularies are closed and why, and what a published version bump may change.
- [The index](https://memhtml.github.io/internals/the-index.md): Two databases on one connection, a schema whose keys expect the primary key to move, and one projection function that makes rebuild and incremental update agree.
- [The memory file format](https://memhtml.github.io/internals/the-memory-file-format.md): A fixed HTML5 vocabulary where every element carries indexing meaning, two hashes with two separate jobs, and a validity check that runs before anything is written.
- [The sleep pipeline](https://memhtml.github.io/internals/the-sleep-pipeline.md): Seventeen curation phases in a fixed order, each an isolated commit on a branch, with commit trailers as the resume mechanism and a quality gate that can refuse the merge.
- [The trace indexer](https://memhtml.github.io/internals/the-trace-indexer.md): A read-only index over session transcripts that stores pointers rather than content, with a table-name firewall keeping it out of retrieval.
- [The write path](https://memhtml.github.io/internals/the-write-path.md): How ordering does the duplicate detection, why a batch is one commit and one index pass, and why the conflict assist only reports.
- [API](https://memhtml.github.io/api.md): The generated reference for the workspace packages, one directory per package and one page per module, built from the TSDoc in the source on every site build.
- [@memhtml/contracts](https://memhtml.github.io/api/contracts.md)
- [edges](https://memhtml.github.io/api/contracts/edges.md)
- [errors](https://memhtml.github.io/api/contracts/errors.md)
- [paths](https://memhtml.github.io/api/contracts/paths.md)
- [slug](https://memhtml.github.io/api/contracts/slug.md)
- [types](https://memhtml.github.io/api/contracts/types.md)
- [@memhtml/domain](https://memhtml.github.io/api/domain.md)
- [@memhtml/eval](https://memhtml.github.io/api/eval.md)
- [@memhtml/llm](https://memhtml.github.io/api/llm.md)
- [@memhtml/traces](https://memhtml.github.io/api/traces.md)
- [Glossary](https://memhtml.github.io/glossary.md): The project's domain vocabulary, one entry each, with the page that develops the term.