# Core Memory CLI Scope

Date: 2026-03-30

## Goal

Define a full-featured Core Memory CLI that makes install, onboarding, inspection,
integration setup, and everyday memory operations easy for both humans and
agents.

This scope is grounded in the current repository state, not a greenfield
rewrite.

## Current State

The current CLI lives in [core_memory/cli.py](../../core_memory/cli.py) and is a
single large `argparse` entrypoint with a broad but hard-to-discover surface:

- top-level verbs like `add`, `query`, `compact`, `consolidate`, `reason`
- nested areas like `sidecar`, `memory`, `graph`, `metrics`, `openclaw`
- mixed user audiences: contributors, operators, framework integrators, agents

Strengths today:

- substantial backend capability already exists
- many useful operations are already scriptable
- OpenClaw onboarding and typed memory execution already have real commands

Current problems:

- P0: the CLI does not currently boot cleanly due to a circular import between
  runtime and integrations modules
- install and first-run workflow are not first-class
- command naming mixes implementation language with user intent
- output is inconsistent across commands
- discoverability is weak because almost everything hangs off one monolithic file
- the CLI exposes low-level internals before it exposes the most common tasks

## Design Principles

1. Default for first success

- a new user should be able to install, initialize, ingest, inspect, and query
  memory in minutes

2. Progressive disclosure

- the happy path should be simple
- advanced graph, metrics, and maintenance tools should remain available without
  dominating the default help surface

3. Stable machine interface

- every command should support a structured output mode suitable for agents and
  shell automation

4. Clear mental model

- commands should map to what users want to do: `init`, `ingest`, `search`,
  `recall`, `doctor`, `integrations openclaw onboard`

5. Modular implementation

- command modules should be split by domain to avoid a permanent monolith

## Target CLI Shape

Proposed canonical entrypoint:

```bash
core-memory <group> <command> [options]
```

User-facing command groups:

- `setup`
- `store`
- `recall`
- `inspect`
- `integrations`
- `ops`
- `dev`

### 1. Setup

Purpose: install, initialize, configure, and validate a local store.

Commands:

- `core-memory setup init`
- `core-memory setup doctor`
- `core-memory setup paths`
- `core-memory setup config show`
- `core-memory setup config set`
- `core-memory setup demo`

Examples:

```bash
core-memory setup init
core-memory setup init --root ./memory
core-memory setup doctor
core-memory setup demo
```

Responsibilities:

- create the memory root and expected directories
- optionally seed demo content
- detect missing files or invalid JSON
- explain the next best command after setup succeeds

### 2. Store

Purpose: create or mutate memory records directly.

Commands:

- `core-memory store add`
- `core-memory store import`
- `core-memory store tag`
- `core-memory store compact`
- `core-memory store uncompact`
- `core-memory store consolidate`
- `core-memory store rolling-window`

Examples:

```bash
core-memory store add --type decision --title "Raised Redis limit" --summary "Pool exhaustion caused failures"
core-memory store compact --session s1 --promote
core-memory store consolidate --session s1 --promote
```

Notes:

- `add` should support both flags and an interactive prompt mode
- `import` should accept JSON, JSONL, and integration event payloads

### 3. Recall

Purpose: retrieve memory with the least possible ceremony.

Commands:

- `core-memory recall search`
- `core-memory recall reason`
- `core-memory recall context`
- `core-memory recall heads`
- `core-memory recall hydrate`

Examples:

```bash
core-memory recall search "redis timeouts"
core-memory recall reason "Why did we change strategy?"
core-memory recall context --query "deploy rollback" --context-tag production
core-memory recall hydrate --turn-id trn_123 --include-tools
```

Notes:

- `search` should be the easiest lexical + typed lookup path
- `reason` remains the explainable recall surface
- `hydrate` wraps transcript/turn recovery without forcing users to know internal APIs

### 4. Inspect

Purpose: understand what is in the store.

Commands:

- `core-memory inspect stats`
- `core-memory inspect list`
- `core-memory inspect show`
- `core-memory inspect graph`
- `core-memory inspect constraints`
- `core-memory inspect health`

Examples:

```bash
core-memory inspect stats
core-memory inspect show bead_123
core-memory inspect list --type lesson --limit 20
core-memory inspect graph stats
```

Notes:

- `list` is friendlier than the current `query` for many users
- `show` should render one bead or turn cleanly
- `health` should include the current canonical-health logic

### 5. Integrations

Purpose: make framework setup easy instead of doc-driven.

Commands:

- `core-memory integrations openclaw onboard`
- `core-memory integrations openclaw doctor`
- `core-memory integrations pydanticai scaffold`
- `core-memory integrations pydanticai validate`
- `core-memory integrations api emit-turn`
- `core-memory integrations migrate rebuild-turn-indexes`

Examples:

```bash
core-memory integrations openclaw onboard --replace-memory-core
core-memory integrations pydanticai scaffold
core-memory integrations api emit-turn --from-file turn.json
```

Notes:

- this is where framework-specific complexity should live
- onboarding should write explicit success/failure guidance, not just raw JSON

### 6. Ops

Purpose: maintenance, upgrades, migrations, and diagnostics.

Commands:

- `core-memory ops doctor`
- `core-memory ops rebuild`
- `core-memory ops migrate`
- `core-memory ops archive rebuild-index`
- `core-memory ops graph sync`
- `core-memory ops metrics report`

Notes:

- this is the natural home for contributor and operator workflows
- `ops` should absorb commands that are currently scattered across top-level verbs

### 7. Dev

Purpose: advanced contributor tools and lower-level experimentation.

Commands:

- `core-memory dev memory form`
- `core-memory dev memory execute`
- `core-memory dev sidecar finalize`
- `core-memory dev sidecar turn`
- `core-memory dev graph infer-structural`
- `core-memory dev metrics autonomy-log`

Notes:

- keep powerful internal tools available without making first-time help overwhelming

## Output Modes

Every user-facing command should support:

- `--format text`
- `--format json`
- `--format jsonl` where streaming is relevant

Default behavior:

- human-readable text by default for terminal users
- deterministic JSON for automation

Additional output conventions:

- `--quiet` for machine-friendly minimal output
- `--verbose` for diagnostics
- non-zero exit codes on failed health/doctor checks
- consistent schemas for JSON output across command groups

## Config Model

The CLI should support configuration from three layers:

1. explicit flags
2. environment variables
3. config file

Proposed config locations:

- local project: `.core-memory.toml`
- user config: `~/.config/core-memory/config.toml`

Key settings:

- `root`
- transcript hydration defaults
- adjacent-turn hydration depth
- semantic model settings
- OpenClaw integration defaults
- output format defaults

## First-Run Experience

The desired journey:

```bash
pip install core-memory
core-memory setup init
core-memory setup doctor
core-memory store add --type lesson --title "Redis timeout" --summary "Pool limit was too low"
core-memory recall search "redis"
```

Better still:

```bash
core-memory setup demo
```

That command should:

- create a demo store
- insert a small realistic memory chain
- print 3-4 next commands the user can try immediately

## Required P0 Fixes Before CLI Expansion

These should happen before major UX work:

1. Fix CLI bootstrap imports

- today `python -m core_memory.cli --help` fails due to a circular import involving:
  - `core_memory.runtime.state`
  - `core_memory.integrations.__init__`
  - `core_memory.integrations.api`
  - `core_memory.runtime.ingress`

2. Split parser registration from execution wiring

- separate parser construction from command handlers
- avoid importing every subsystem at startup

3. Add smoke tests for help surfaces

- `core-memory --help`
- `core-memory setup --help`
- `core-memory recall --help`
- `core-memory integrations openclaw --help`

## Recommended Implementation Architecture

Suggested package layout:

```text
core_memory/cli/
  __init__.py
  main.py
  context.py
  formatting.py
  config.py
  groups/
    setup.py
    store.py
    recall.py
    inspect.py
    integrations.py
    ops.py
    dev.py
```

Migration approach:

- keep `core_memory.cli:main` as the entrypoint for compatibility
- move implementation behind a new package-backed command registry
- preserve existing verbs with deprecation aliases where practical

## Command Mapping From Current Surface

Current to proposed:

- `add` -> `store add`
- `query` -> `inspect list`
- `stats` -> `inspect stats`
- `doctor` -> `setup doctor` and `ops doctor`
- `heads` -> `recall heads`
- `retrieve-context` -> `recall context`
- `reason` -> `recall reason`
- `compact` -> `store compact`
- `consolidate` -> `store consolidate`
- `rolling-window` -> `store rolling-window`
- `openclaw onboard` -> `integrations openclaw onboard`
- `memory form` -> `dev memory form`
- `memory execute` -> `dev memory execute`
- `graph *` -> `inspect graph` or `ops graph`
- `metrics *` -> `ops metrics` or `dev metrics`

## Phased Delivery Plan

### Phase 1: Stabilize and Reframe

- fix the circular import so help and basic commands work
- introduce grouped help surface
- add `setup init`, `setup doctor`, `inspect stats`, `recall search`
- preserve old commands as compatibility aliases

Success criteria:

- first-time user can initialize and inspect a store without reading source code
- `--help` works everywhere

### Phase 2: First-Class Onboarding

- add demo mode
- add interactive `store add`
- add guided OpenClaw onboarding diagnostics
- add config file support

Success criteria:

- a new user can go from install to working example in under five minutes

### Phase 3: Integration Ergonomics

- add PydanticAI scaffold/validate flows
- add import/export helpers
- add transcript hydration and turn inspection UX

Success criteria:

- framework adoption becomes command-driven instead of doc-heavy

### Phase 4: Power User Surfaces

- move graph and metrics into clear `inspect` and `ops` homes
- add richer filtering, paging, and rendering
- add shell completions and command examples

Success criteria:

- advanced operators keep all current power, but the interface becomes understandable

## Immediate Next Build Slice

The best first implementation slice is:

1. fix CLI bootstrap so `--help` works
2. add a grouped command shell with `setup`, `store`, `recall`, `inspect`
3. wire existing handlers behind aliases rather than rewriting behavior first
4. add smoke tests for grouped help and one happy-path command per group

This gives the repo a better UX quickly without pausing backend feature work.

## Bottom Line

Core Memory already has enough backend capability for a strong CLI. The next step
is not adding more verbs. It is reorganizing the existing power into a command
surface that makes the first ten minutes feel obvious, safe, and productive.
