# haft: Engineering Decision Memory with Evidence Decay for AI Coding Agents

> haft is a local Go tool that gives AI coding agents a durable, typed memory of engineering decisions. It records what problem is being solved, which options were compared, which decisions the human made, what evidence supports them, and which decisions have since become stale. Claude Code and Codex are the stable supported hosts; Cursor, Gemini CLI, Grok, and others are experimental adapters.

**m0n0x41d/haft** — Engineering decisions engine that know when they're stale. Frame, compare, decide — with evidence decay and parity enforcement. For Claude Code, Cursor, Gemini CLI, Codex and more.

- Repository: https://github.com/m0n0x41d/haft
- Website: https://haft.tools
- Stars: 1,393 · Forks: 102
- Language: Go
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/m0n0x41d-haft

## What haft Is and What Problem It Solves

AI coding agents work in sessions. When a session ends, the conversation history goes with it. Decisions made about the architecture, the choice of library, the data model, or the API design exist only in chat logs unless someone writes them down. The next session starts without knowing what was already considered, what was rejected, and why.

haft addresses this by maintaining a local SQLite database of typed project records. It stores what problem is being solved, which options were compared for a decision, what evidence the human cited when choosing one, and whether that evidence has since become stale. The README calls this the governance layer: not the agent's running context, but the record of results that later work must rely on. Small, reversible reasoning can stay in conversation; load-bearing decisions become typed project records.

The framework is grounded in the First Principles Framework (FPF), a systems architecture methodology developed by Anatoly Levenchuk. The README describes FPF as a rigorous architecture for thinking about systems and describes haft as the practical handle that brings versioned FPF source into the agent's working context alongside the project-local skills and MCP gates.

## Project Memory Architecture: Artifacts, Evidence Decay, and the SQLite Ledger

haft stores its structured data in a SQLite database at ~/.haft/projects/<id>/. The database holds the artifact graph, baselines, indexes, and runtime state that agents query through the CLI and MCP server. The README describes the footprint as local-first but not zero: haft init creates markdown carriers in a .haft/ directory in the project root and the project database under the home directory path.

Evidence decay is a first-class concept in the model. When a decision record is created, it carries the evidence that supported it at the time. As the project changes, that evidence can become stale: a benchmark is no longer valid, a third-party library has changed its API, or a constraint no longer exists. haft tracks this staleness so the agent can flag decisions that may need reconsideration rather than blindly relying on outdated rationale.

Parity enforcement is the second distinctive mechanism mentioned in the repository description. The README does not expand on the exact definition of parity in this context beyond citing it as a property the system enforces alongside evidence decay.

## Installing haft and Initializing a Project

Installation is a single curl command:

```bash
curl -fsSL https://raw.githubusercontent.com/m0n0x41d/haft/main/install.sh | bash
```

For a project that has not used haft before, initialize it once:

```bash
haft init
```

Bare haft init opens an interactive multi-select when stdin and stdout are terminals. In scripts and CI, the host must be specified explicitly:

```bash
haft init --core-only        # Project core and ledger, no host carriers
haft init --claude           # Claude MCP + skills + CLAUDE.md section
haft init --codex            # Codex MCP + skills + AGENTS.md section
haft init --claude --local   # Claude integration with repo-local skills
haft init --codex --local    # Codex integration with repo-local skills
```

Any explicit init flag skips the menu and executes its declared behavior. Bare non-interactive invocation fails before writing any files rather than guessing a host. Re-running haft init on an already-initialized project replaces recognized legacy Haft skills and updates only the content between the <!-- haft:start --> and <!-- haft:end --> markers in project instruction files; content outside those markers is project-owned and not touched.

## Host Adapter Configuration for Claude Code, Codex, and Others

haft's initialization output varies by host. For Claude Code, it writes to .mcp.json, installs skills to ~/.claude/skills/ (or .claude/skills/ with --local), and adds a managed section to CLAUDE.md. For Codex, it writes to .codex/config.toml, installs skills to ~/.agents/skills/ (or .agents/skills/ with --local), and adds a managed section to AGENTS.md.

Project-scoped configuration files (.mcp.json, .codex/config.toml, .grok/config.toml) use portable project-root paths and are safe to commit for shared repositories. Zed and Antigravity settings are global and may start MCP or context servers outside the workspace directory.

The README lists Claude Code and Codex as the two stable supported hosts. Grok, Pi, Hermes, Zed, Antigravity, Cursor, Gemini CLI, and OpenCode are experimental or legacy adapters. For Cursor specifically, after running haft init --cursor, Settings -> MCP -> find haft -> enable the toggle must be done manually, because Cursor adds MCP servers in a disabled state by default.

## Database Migrations and Version Stability

haft manages its SQLite schema through version boundaries. When a new binary starts, it applies only migration boundaries that the release explicitly marks as startup-safe. The README documents the current chain as covering schema versions 57 to 58 and 58 to 59. At each boundary it crosses, haft publishes a verified SQLite snapshot beside the project ledger before applying the migration.

For manual migration boundaries (those not marked startup-safe), the README provides an exact fallback command pattern:

```bash
haft project migrate --project-root /absolute/project/root --project-id qnt_........
```

The README includes a caution: future-schema, missing-binding, integrity, and stale WAL/SHM diagnostics each have different recovery paths. Running a generic migration command in response to those errors is incorrect. The README also specifies that re-running haft init is not routine database maintenance.

## What haft Does Not Cover

haft is not a general code review or CI gate tool. It does not run tests, analyze diffs, or block pull requests. Its scope is the decision record layer: it persists what was decided and why, not whether the implementation is correct.

The database is local and not committed to the repository. Teams where multiple developers work on the same codebase would each have their own local haft database. The README does not document a mechanism for synchronizing haft databases between developers. For shared decision records, some other documentation approach (a decision record in docs/, an architecture decision record committed to the repository) would be needed in parallel.

The license file is present in the repository but the README does not state the license. go.mod requires go 1.25.8. The most recent release is v9.1.0, published on 2026-08-11, and the last push to the repository was on 2026-09-24.

## Compared to a Plain AGENTS.md or CLAUDE.md File

AGENTS.md and CLAUDE.md files provide the agent with context about the project: its stack, commands, conventions, and background. They are static documents that the engineer maintains by hand. They do not track individual decisions, the options that were rejected, the evidence cited, or whether any of that has become stale.

haft adds a structured, queryable layer on top of plain instruction files. The agent can ask the haft MCP server about past decisions for a given component and get a typed, timestamped record rather than scanning a Markdown document. The managed sections that haft writes to CLAUDE.md and AGENTS.md are minimal pointers that tell the agent how to query the haft MCP server, not the full decision record. The decision content lives in the SQLite database, not in the instruction file.

## Conclusion

Engineering teams using Claude Code or Codex who make architectural decisions in the course of AI-assisted work and want those decisions to remain accessible to the agent across sessions will find haft the only purpose-built tool for this. Teams on experimental hosts (Cursor, Gemini CLI, Grok) should expect rougher edges and read the per-host caveats in the README before committing to it. Before adopting haft on an existing project, run haft init once to create the .haft/ markdown carriers and the project SQLite database, then check whether your team's .gitignore strategy accommodates the ~/.haft/projects/ path, since the database is local and not committed to the repository.

## FAQ

### What is haft and what does it do for AI coding agents?

haft is a local Go tool that maintains a SQLite database of engineering decisions for AI coding agents. It records the problem being solved, the options that were compared, the decision made, and the evidence supporting it, then tracks whether that evidence has become stale as the project evolves.

### Does haft work with Cursor?

Cursor is listed as an experimental adapter. Run haft init --cursor to generate the configuration, then manually enable the haft MCP server in Cursor's Settings -> MCP panel, since Cursor adds MCP servers in a disabled state by default.

### Where does haft store its data?

haft creates markdown carriers in a .haft/ directory in the project root and a project SQLite database at ~/.haft/projects/<id>/ in the user's home directory. The database is local and is not committed to the repository.

## Sources

- [Issues](https://github.com/m0n0x41d/haft/issues)
- [m0n0x41d/haft on GitHub](https://github.com/m0n0x41d/haft)
- [Project website](https://haft.tools)
- [README](https://github.com/m0n0x41d/haft/blob/main/README.md)
- [Releases](https://github.com/m0n0x41d/haft/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/m0n0x41d-haft