# agentmemory Command Design

## Concepts

### Beliefs
Everything the memory system stores as "knowledge" is a belief. A belief has:
- **Content** -- the text of what's believed
- **Confidence** -- a Bayesian score (Beta distribution) that starts at a prior and updates over time as evidence accumulates
- **Type** -- factual, preference, correction, requirement, etc.
- **Source** -- where it came from (user stated, agent inferred, document, git, etc.)

All beliefs generated by the system (from onboarding, conversation ingestion, etc.) are regular beliefs. They get assigned priors by the classification module and percolate up or down via the Bayesian updater based on evidence.

### Locked beliefs
The only way a belief becomes locked is through explicit user action via `/mem:lock`. Locked beliefs:
- Cannot have their confidence reduced by negative feedback
- Always surface in retrieval results regardless of query
- Override any conflicting non-locked beliefs

Nothing in the system auto-creates locked beliefs. Not corrections, not high confidence, not repeated reinforcement. Only the user locks beliefs.

### Core beliefs
The highest-confidence beliefs in the system, regardless of lock status. These are what the system is most sure about. `/mem:core` shows these -- the system's best knowledge at a glance.

**Core = "what the system knows best." Locked = "what the user declared as absolute rules."**

### Deletion / forgetting
Belief deletion requires careful design to preserve graph integrity, privacy, and security. Not in scope for initial release. When designed, must address:
- Graph edge integrity (what happens to edges pointing to/from deleted beliefs?)
- Privacy guarantees (is the data actually gone, or just hidden?)
- Security (who can delete? audit trail?)

---

## Commands

### /mem:onboard <path>
**Purpose:** First-time ingestion of a project into memory.
**What it does:**
1. Scans the project directory for signals (git, docs, code, directives)
2. Extracts nodes (commits, sentences, functions, directives)
3. Feeds extracted content through the classification pipeline
4. Creates observations and beliefs in the store (all as regular beliefs with classification-assigned priors)
**When to use:** When starting to use agentmemory on a new project.
**CLI:** `agentmemory onboard <path>`

### /mem:status
**Purpose:** Quick health check of the memory system.
**What it does:** Shows counts of observations, beliefs, locked beliefs, superseded beliefs, edges, sessions.
**When to use:** To verify the system is working or see how much is stored.
**CLI:** `agentmemory status`

### /mem:stats
**Purpose:** Detailed analytics about the belief store.
**What it does:** Shows confidence distribution, beliefs by type, beliefs by source, age distribution, and other numerical breakdowns.
**When to use:** When you want the numbers.
**CLI:** `agentmemory stats`

### /mem:health
**Purpose:** Diagnostic check of the memory system.
**What it does:** TODO: implement diagnostics. For now, shows the same analytics as /mem:stats with a placeholder for diagnostic checks (orphaned beliefs, graph connectivity issues, stale sessions, etc.).
**When to use:** When something seems wrong and you want to investigate.
**CLI:** `agentmemory health`

### /mem:core [N]
**Purpose:** Show the top N most important beliefs the system holds.
**What it does:**
1. Retrieves all beliefs, scores them by confidence
2. Returns the top N (default 10) in ranked order
3. Shows content, confidence, type, and whether locked
**When to use:** To see what the system "knows" about the project at a glance. Good for verifying the system absorbed the right things after onboarding.
**CLI:** `agentmemory core [--top N]`
**Default N:** 10. Configurable.

### /mem:search <query>
**Purpose:** Find beliefs relevant to a query.
**What it does:** Runs FTS5 search + Bayesian scoring + compression, returns ranked results within a token budget.
**When to use:** When you want to know if the system remembers something specific.
**CLI:** `agentmemory search <query>`

### /mem:locked
**Purpose:** Show all locked beliefs (hard constraints).
**What it does:** Lists every belief with locked=True that hasn't been superseded.
**When to use:** To review what rules/constraints the system is enforcing.
**CLI:** `agentmemory locked`

### /mem:new-belief <text>
**Purpose:** Manually store a new belief.
**What it does:** Creates a regular belief with a high prior (alpha=9.0, beta=0.5). NOT locked -- it enters the system as a strong belief that can still be updated by evidence.
**When to use:** When you want to tell the system something it should know.
**CLI:** `agentmemory remember <text>`

### /mem:lock <statement>
**Purpose:** Create a locked belief (non-negotiable constraint).
**What it does:** Creates a belief with locked=True. This is the ONLY way beliefs become locked.
**When to use:** When you want to establish an absolute rule the agent must always follow.
**CLI:** `agentmemory lock <text>`
**Note:** Promotion from existing belief to locked is a future feature. Requires a visualization/selection layer since belief IDs are not human-friendly. For now, `/mem:lock` creates new locked beliefs from scratch.

### /mem:help
**Purpose:** Show available commands and brief descriptions.
**What it does:** Prints the command reference.
**CLI:** `agentmemory help`

---

## Decisions made

- **No /mem:correct command.** The implementation (auto-guessing which belief to replace) is too convoluted for the value it provides. Corrections flow through the normal ingestion pipeline as regular beliefs.
- **No /mem:forget command (yet).** Deletion requires deliberate design for graph integrity, privacy, and security. Deferred.
- **Nothing auto-creates locked beliefs.** Only `/mem:lock` does.
- **All other beliefs are regular.** Priors assigned by classification module, confidence updated by Bayesian updater.
- **/mem:stats = numbers. /mem:health = diagnostics.** Stats is analytics, health is "is anything broken?"

## Future work (out of scope)

- **Belief promotion (core -> locked).** Needs a visualization/selection layer. IDs are not human-trackable. Maybe a TUI, maybe a numbered list in `/mem:core` that you can reference.
- **Deletion protocol.** Privacy, security, graph integrity.
- **Visualization layer.** For browsing, promoting, and managing beliefs interactively.

---

## Installation flow

See INSTALL_PATTERN.md for research findings.

**Target experience:**
```
uv tool install agentmemory
agentmemory setup
```

The `setup` command:
1. Creates `~/.claude/commands/mem/*.md` (slash commands)
2. Writes MCP server config
3. Verifies the MCP server starts and responds
4. Prints confirmation with next steps

Must work on the first try. Zero manual configuration. If any step fails, it explains exactly what went wrong and how to fix it.

After setup, the user restarts Claude Code and runs `/mem:onboard .` on their project.
