The idea
You can't recall what you don't know you know.
An agent can have the right memory stored perfectly and still fail to use it because retrieval begins with a cue. MemHooks stores that cue close to the code or folder where it matters.
Memory systems know how to remember. MemHooks tells the agent what to recall here.
When an agent works in a directory, MemHooks resolves the applicable MEMHOOKS.md files from repository root to that directory, applies role routing, and produces a bounded retrieval plan for whatever memory backend the runtime actually uses.
workspace/
├── MEMHOOKS.md
├── backend/
│ ├── MEMHOOKS.md
│ └── auth/
│ ├── MEMHOOKS.md
│ └── refresh.py
Working in backend/auth/ means:
root hook
↓ inherit
backend hook
↓ inherit
local auth hook
↓
resolve + apply role routing
↓
hand backend-neutral intent + provider hints to the runtime
↓
recall bounded relevant context
↓
do the work
Who does what?
Normal users generally do not hand-maintain MEMHOOKS.md.
- User: installs/enables MemHooks and may choose or configure a memory backend.
- Agent/runtime: creates and maintains local retrieval cues as work evolves, and decides which backend is active.
- MemHooks reference engine: parses, inherits, validates, filters, explains, and preserves provider-specific hints without interpreting them.
- Memory backend: stores and retrieves the actual memories.
The hook files are infrastructure for agents. Advice about pruning, cue quality, or routing-file size is therefore directed at agents/runtime authors, not at end users.
v0.5.0: genuinely backend-neutral
memhooks/v2 separates universal retrieval intent from provider-native controls.
The core understands only concepts that are useful regardless of memory vendor:
recall_queries- query
priority when.rolesentitiesresourcestagsexcludescopesensitivity- filesystem inheritance
Anything native to a particular memory system belongs under:
backends:
<provider>:
... provider-owned configuration ...
MemHooks deliberately does not know what those provider keys mean.
Example
---
schema: memhooks/v2
inherits: true
scope: backend/auth
recall_queries:
- query: "Why did the authentication design change after the outage?"
priority: 1.0
when:
roles:
entities:
- Authentication
resources:
- name: auth-postmortem
kind: postmortem
salience: 0.9
tags:
backends:
mem0:
top_k: 8
rerank: true
hindsight:
memory_types:
connection_types:
strategy: reflect
entities:
- name: Authentication
type: CONCEPT
salience: 0.95
resources:
- auth-architecture
tags:
exclude:
- obsolete OAuth prototype
backends:
mem0:
filters:
user_id: auth-agent
hindsight:
bank: project-memory
---
Here priority, roles, entities, resources, tags, and exclusions are MemHooks concepts. top_k, rerank, Mem0 filters, Hindsight memory types, bank, and reflect are not. They are opaque provider hints carried under their own namespace.
Provider namespaces
v0.5.0 ships first-class reference mappings for:
These mappings explain how an adapter can interpret its own namespace. The Rust core treats all backend namespace contents as opaque YAML mappings.
Merge behavior for provider hints
Provider mappings inherit root → leaf just like the surrounding hook chain, but MemHooks does not invent provider semantics:
- mapping/object values are recursively merged;
- a more local scalar replaces the parent scalar;
- a more local list replaces the parent list;
- query-local
backends.<provider>overlays the resolved scope-level provider configuration.
That gives adapters predictable configuration without pretending MemHooks understands every provider API.
Install the Rust tooling
CLI
Useful commands:
Rust library
A Rust runtime can use the reference resolver directly instead of reimplementing inheritance and role-routing semantics.
For this release specifically:
The reference implementation does not contact a memory backend and does not execute commands from hook files. It resolves retrieval intent and provider configuration; the host runtime performs retrieval.
Core fields at a glance
| Field | Meaning |
|---|---|
schema |
currently memhooks/v2 |
inherits |
inherit ancestor hooks; defaults to true |
scope |
optional backend-neutral scope label |
recall_queries |
concrete questions worth asking memory |
recall_queries[].priority |
optional 0.0..1.0 importance under context pressure |
recall_queries[].when.roles |
optional exact-string role applicability |
entities |
named retrieval cues, optionally with open type and salience |
resources |
named existing resources, optionally with open kind and salience |
tags |
backend-neutral routing/relevance labels |
exclude |
obsolete or misleading context to keep out |
sensitivity |
advisory handling metadata |
backends |
opaque provider namespaces interpreted by adapters, not by the core |
The normative contract is references/memhooks-format.md.
Root-to-leaf behavior
Given:
/repo/MEMHOOKS.md
/repo/backend/MEMHOOKS.md
/repo/backend/auth/MEMHOOKS.md
an agent working in /repo/backend/auth/ resolves all three in that order unless a local inherits: false cuts off the parent chain.
Core lists accumulate with exact duplicate removal; more local scalar core values win. Query-local entities/resources/tags supplement inherited core cues. Role filtering happens after inheritance resolution when active roles are actually known.
Provider namespace mappings use the merge behavior described above.
Hermes / Hermes Desktop
Clone the skill:
Install the lifecycle hooks:
Add to ~/.hermes/config.yaml:
hooks:
pre_llm_call:
- command: "python3 ~/.hermes/agent-hooks/memhooks_pre_llm.py"
timeout: 5
post_tool_call:
- command: "python3 ~/.hermes/agent-hooks/memhooks_update.py event"
timeout: 5
Then enable it once inside a project:
/memhooks init
After initialization, the runtime/agent maintains the routing cues. See hooks/hermes/README.md.
Documentation
- Documentation index
- Quickstart
- CLI reference
- Rust library/API guide
- Agent integration guide
- Protocol guide
- Troubleshooting
What MemHooks is not
MemHooks is not a vector database, memory provider, automatic memory-writing system, GraphRAG framework, prompt-privilege mechanism, shell-command manifest, or background daemon.
It is deliberately narrow infrastructure:
When an agent works here, remember these things first.
Related: Token Terminator
If MemHooks is about retrieving the right context, Token Terminator is about not wasting tokens on the wrong context.
Status
v0.5.0 — experimental backend-neutral retrieval-routing protocol + Rust reference resolver/linter + deterministic agent-maintenance runtime.
License
MIT © 2026 Aron Bijl