Project memory
Chat history is useful context, but it is weak project memory. It mixes questions, guesses, recommendations, decisions, plans, reports, and stale facts in one stream. Semantic search can retrieve a related paragraph; it still does not tell the agent what kind of statement it found or whether the project should rely on it now.
Haft stores the important parts as different, related project records so the memory preserves what each statement is allowed to mean.
The minimum grammar
| Record | What it preserves |
|---|---|
| Problem | What is wrong or uncertain, the scope, constraints, and acceptance |
| Options | Distinct approaches, trade-offs, and weakest links |
| Decision | The human's selected option, rationale, scope, and revisit condition |
| Specification | The current product or software contract |
| Evidence | An observation that supports or weakens a claim for a stated use and time |
| Note | A non-binding fact, caveat, or rationale worth retaining |
| Code link | Where a decision, specification, or invariant may meet the implementation |
These records can refer to one another without becoming interchangeable. A decision does not prove implementation. A specification does not execute code. Evidence does not choose a product direction. A markdown file carries a record; it is not the product or code the record describes.
When Haft writes memory
Haft keeps ordinary local reasoning in the conversation. Durable memory is justified when you explicitly ask to save or bind something, or when the current work has a concrete later use: handoff, another session, audit, automation, delayed evidence, or an expensive reversal.
“The graph is empty” and “this might be useful someday” are not enough. When persistence is useful, Haft should create only the records needed by that later use—not an automatic problem-to-plan paperwork bundle.
Where the data lives
- Local structured state lives in SQLite under
~/.haft/projects/<project-id>/. - Reviewable project files live under
.haft/. - The code index connects files and symbols to project records.
- A small user-local cross-project index stores decision summaries for recall.
The readable files make records inspectable in a repository. SQLite is the local structured store used by the running tools. A file being present in git does not by itself make another engineer's local database current.
Advanced: the exact thing currently in question
In the v9 model, an EntityOfConcern is the exact project thing
around which Haft gathers memory: for example, a billing policy, API
boundary, cache, service responsibility, or decision subject. The awkward
name matters mainly to the implementation. As a user, the useful question
is: “Which exact thing are we talking about, in which project context?”
Haft resolves a known name or alias, selects one exact identity for the current use, and reads the smallest relevant neighborhood. Similar names, file paths, or retrieval scores never merge two project things automatically.
haft memory resolve --input-file resolve.json
haft memory neighborhood --input-file neighborhood.json
haft memory recall --input-file recall.jsonAdvanced: project setup and memory models
haft init installs the default project-memory model
automatically. For a simple supported codebase, Haft can detect one stable
software scope and bootstrap its profile. Mixed, truncated, or genuinely
multi-scope projects may require a human to identify the intended scope.
Users are not asked to select an internal schema.
When Haft ships a newer bundled memory model, every successor proven compatible with the current project state is activated automatically. An incompatible, incomplete, stale, or underdetermined candidate leaves the current model unchanged and reports why. Rollback and selecting an incompatible model remain explicit operations.
Public v9 identity changes are alias-only: an alias can be admitted or superseded with provenance. Automatic entity merge and split are not part of the current contract.
Setup ready has a narrow meaning. It says that the project profile and memory model are available. It does not say that the specifications are healthy, the code is correct, or the evidence is current.
The trade-off
Typed memory makes category mistakes, missing context, and stale evidence easier to notice. It also makes missing or ambiguous identity visible instead of letting fuzzy recall smooth it over. The result can feel slower than “find something related,” but it is safer when later work will rely on the distinction.