memhooks 0.6.0

Backend-neutral parser, resolver, validator, maintainer, and CLI for filesystem-scoped AI agent memory routing
Documentation
# MemHooks documentation

MemHooks is a filesystem-scoped, **backend-neutral retrieval-routing protocol** for AI agents. These guides cover `memhooks/v2`, the Rust reference resolver/validator/maintainer, runtime integration, security boundaries, and provider adapter mappings.

## Wiki

For the more approachable, cross-linked explanation of MemHooks, start with the [Wiki source](../wiki/Home.md). The repository keeps the Wiki source version-controlled under `wiki/` and can mirror it to GitHub's Wiki tab.

The Wiki is explanatory. The normative protocol contract remains [`references/memhooks-format.md`](../references/memhooks-format.md).

## Start here

- [Quickstart]quickstart.md — enable MemHooks and understand what happens automatically.
- [CLI reference]cli.md — `memhooks init`, `note`, `event`, `validate`, and `explain`.
- [Rust library guide]rust-library.md — call the reference parser/resolver/maintainer directly from Rust.
- [Agent integration guide]integrating-an-agent.md — wire MemHooks into an agent runtime/harness.
- [Protocol guide]protocol-guide.md — practical `memhooks/v2` core, root, inheritance, and backend namespace semantics.
- [Troubleshooting]troubleshooting.md — validator diagnostics and common failure modes.
- [Publishing the Rust crate]publishing.md — maintainer notes for crates.io releases.
- [Security policy]../SECURITY.md — trust boundary and private vulnerability reporting.
- [Contributing]../CONTRIBUTING.md — test/review expectations.

## Who maintains hook files?

Ordinary users normally **do not** hand-maintain `MEMHOOKS.md`.

The normal division is:

1. the user enables MemHooks and optionally configures a memory backend;
2. the agent/runtime creates and updates local retrieval cues through the reference maintainer;
3. the reference engine writes, validates, resolves, and explains the same YAML frontmatter data model;
4. the active memory adapter performs bounded retrieval.

Operational advice about keeping cues concise, pruning stale routing, and choosing provider hints is therefore documented in agent/runtime material rather than presented as a user chore.

## One structured data path

v0.6.0 deliberately has one normative structured store:

```text
memhooks note / memhooks event
        ↓
YAML frontmatter
        ↓
reference parser/resolver
        ↓
memhooks explain / Rust API
        ↓
runtime adapter
```

The Markdown body remains source-attributed free-form guidance. It is not a second machine-routing store.

## Canonical specification

The normative format contract is [`references/memhooks-format.md`](../references/memhooks-format.md). If an explanatory guide conflicts with that reference, the reference wins.

## Provider mappings

Provider-native vocabulary lives only inside provider namespaces:

- [Hindsight]../references/memory-systems/01-hindsight.md — `backends.hindsight`
- [OpenViking]../references/memory-systems/02-openviking.md — `backends.openviking`
- [Honcho]../references/memory-systems/03-honcho.md — `backends.honcho`
- [Mem0]../references/memory-systems/04-mem0.md — `backends.mem0`
- [Generic / unknown backend]../references/memory-systems/99-generic-or-unknown.md

## Runtime-specific documentation

- [Hermes / Hermes Desktop integration]../hooks/hermes/README.md

## Design boundary

MemHooks does **not** become a memory database, lowest-common-denominator provider API, shell-command manifest, prompt-privilege system, or daemon.

The core answers:

> **What should the agent remember here?**

Provider namespaces answer:

> **How should this particular memory backend help retrieve it?**

The host runtime still owns memory access, credentials, trust policy, execution, prompt construction, and context-budget enforcement.