# Memory Maintenance Decision Schema

## Purpose

This schema is for the post-install maintenance loop of the Agent Memory Move.
It ensures memory is not only measurable, but that the measurements directly inform decisions.

## Core principle

We are not guessing from feel.
We are capturing evidence, tabulating it, and using the results to decide what to keep, prune, retag, merge, split, or tune.

```text
measure → tabulate → compare → decide → tune → repeat
```

## What to record

Each maintenance event should be one row.

### Required fields

| Field | Type | Purpose |
|---|---|---|
| `timestamp` | ISO datetime | When the event occurred |
| `layer` | enum | `archive`, `candidate`, `approved_memory`, `hermes_native`, `open_brain`, `mcp`, `retrieval` |
| `surface` | enum | `WebUI`, `Telegram`, `notion`, `cli`, `other` |
| `event_type` | enum | `search`, `fetch`, `install`, `prune`, `retag`, `merge`, `split`, `approve`, `reject`, `edit`, `source_only`, `tune` |
| `query_or_action` | text | What was searched, fetched, or changed |
| `expected_result` | text | What we predicted would happen |
| `actual_result` | text | What actually happened |
| `match_quality` | enum | `excellent`, `good`, `mixed`, `poor`, `miss`, `noise` |
| `decision_action` | enum | `keep`, `prune`, `promote`, `demote`, `retune`, `no_change` |
| `memory_type` | text | The memory type involved |
| `project` | text | Project/domain if applicable |
| `source_id` | text | Source chunk / candidate / memory ID |
| `confidence` | enum | `high`, `medium`, `low` |
| `sensitivity` | enum | `public`, `private`, `sensitive`, `restricted` |
| `notes` | text | Freeform observation |

## Example row

| timestamp | layer | surface | event_type | query_or_action | expected_result | actual_result | match_quality | decision_action | memory_type | project | source_id | confidence | sensitivity | notes |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2026-05-28T10:00:00-04:00 | open_brain | WebUI | search | `Barely, But Here not-fun places` | find the voice rule quickly | found exact approved memory plus source excerpt | excellent | keep | writing_voice | Barely, But Here | candidate-id-or-memory-id | high | sensitive | good retrieval, no tuning needed |

## Decision rules

Use the data to decide:

- **keep**: the memory is accurate, useful, and stable
- **prune**: it is stale, noisy, redundant, or no longer useful
- **promote**: move from source-only or candidate into approved memory
- **demote**: remove from high-priority memory if it creates noise
- **retune**: change chunking, tags, query shape, ranking, or access routing
- **no_change**: retain current state

## Trend questions to answer

The table should help answer questions like:

- Which memory types produce the best retrieval quality?
- Which queries are consistently noisy?
- Which source types become useful memory most often?
- Which items should stay source-only rather than become approved memory?
- Which layers need the most tuning during the first week?
- Does one surface (WebUI vs Telegram) need different retrieval defaults?
- Are we over-promoting sensitive material?
- Are we missing tangential context that should have been indexed or retained?

## Cadence suggestions

Cadence should be tuned after live usage begins.
Initial suggestion:

- **hourly** during early install/stabilization if the system is actively being exercised
- **daily** during the first adjustment period
- **weekly** once the system settles

## Outcome categories

Each maintenance review should end with one of these outcomes:

- `ok`
- `needs-tuning`
- `needs-pruning`
- `needs-reindexing`
- `needs-retagging`
- `needs-more-data`

## Assessment output

Every maintenance cycle should produce a short assessment:

- what the data says
- what pattern is emerging
- what risk or opportunity is visible
- how confident the assessment is

## Suggestion output

Every maintenance cycle should also produce recommendations such as:

- keep as-is
- prune
- promote
- demote
- retag
- merge
- split
- reindex
- change cadence
- collect more data before deciding

The point is for the system to recommend next actions, not just report numbers.

## Why this matters

The goal is not merely to know that memory exists.
The goal is to use measurement to improve decisions.

That means the memory architecture should act like an operating system for contextual recall:

```text
observed behavior → stored evidence → decision → next configuration
```

## Related project docs

- `current-memory-status-pre-install.md`
- `agent-memory-move-exact-install-spec.md`
- `proposed-first-install-batch.md`
- `memory-review-workflow.md`
- `memory-scope-and-review-governance.md`