memhooks 0.5.0

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

The `memhooks` binary is the reference command-line resolver and validator for `MEMHOOKS.md` using `memhooks/v2`.

## Commands

```text
memhooks validate [PATH] [--all] [--format human|json|sarif]
memhooks explain [PATH] [--role ROLE ...] [--format human|json]
```

`PATH` defaults to the current directory.

## `memhooks validate`

Validate one file, a subtree, or an entire repository.

```bash
memhooks validate
memhooks validate backend/auth
memhooks validate backend/auth/MEMHOOKS.md
memhooks validate --all
```

With `--all`, MemHooks resolves the repository root and scans below it while respecting Git ignore rules.

### Output formats

```bash
memhooks validate --all --format human
memhooks validate --all --format json
memhooks validate --all --format sarif
```

Human is the default. JSON is suitable for tooling. SARIF is suitable for code-scanning/CI pipelines.

### Exit status

- `0` — no validation errors; warnings may still be present.
- `1` — at least one validation error exists.

The validator checks the v2 **core** plus the structural shape of backend namespaces. It deliberately does not validate arbitrary provider-internal keys inside `backends.<provider>`.

A provider adapter may run additional provider-specific validation separately.

## `memhooks explain`

`explain` resolves the effective root-to-leaf routing configuration for a target path.

```bash
memhooks explain backend/auth
```

Human output includes:

- resolved repository root;
- target path;
- source `MEMHOOKS.md` files in inheritance order;
- active roles when supplied;
- effective recall queries and source provenance;
- explicit query priority when present;
- role applicability;
- resolved backend namespace names;
- entity/resource/exclusion counts.

### Role filtering

```bash
memhooks explain backend/auth --role reviewer
memhooks explain backend/auth --role reviewer --role architect
```

Role matching is exact-string OR matching. A query with no `when.roles` applies universally. If no active roles are supplied, role-restricted queries are preserved rather than discarded.

### JSON explain output

```bash
memhooks explain backend/auth --role reviewer --format json
```

The JSON object exposes:

- `root`
- `target`
- `sources`
- `scope`
- `sensitivity`
- `entities`
- `resources`
- `tags`
- `exclude`
- resolved scope-level `backends`
- `active_roles`
- effective `recall_queries`

Each effective structured query carries its merged generic cues and effective provider namespaces. This makes the JSON form useful as a handoff from the reference resolver to runtime adapters.

## Provider configuration in explain output

The CLI **shows** provider configuration but does not interpret it.

For example:

```yaml
backends:
  mem0:
    top_k: 8
  hindsight:
    memory_types: [experience]
```

will appear in the resolved output as provider-owned data. The CLI does not decide what `top_k` or `memory_types` means.

## CI example

```yaml
- name: Validate MemHooks
  run: memhooks validate --all
```

To emit SARIF:

```bash
memhooks validate --all --format sarif > memhooks.sarif
```

## What the CLI does not do

The CLI does not:

- contact Hindsight, Mem0, OpenViking, Honcho, or another memory backend;
- validate arbitrary provider-native keys inside a provider namespace;
- execute commands declared by hook files;
- create or modify memories;
- decide prompt privilege/injection level;
- start a background daemon.

It is deliberately limited to parsing, core validation, inheritance resolution, role filtering, opaque provider configuration merging, and explanation.