memops

A read-only memory integrity doctor for file-backed agent workspaces.

What memops IS:

• A local-first CLI that verifies memory system health
• A structural integrity checker for file-backed workspaces
• An operational tool for agents and the operators who run them

What memops IS NOT:

• Not a memory engine
• Not a vector database
• Not a second-brain app
• Not a memory management system
• Not a replacement for OpenClaw, Mem0, Zep, or MemGPT

Why this exists

Memory-backed agents rely on durable files. When those files go missing, get corrupted, or drift out of sync, the agent loses context. You need a way to verify the memory substrate is intact before trusting it.

memops exists to give operators and agents a fast, read-only sanity check. Run it before critical operations. Use it in CI. Use the output as a structural health signal before trusting the workspace.

What v0.1 does not do

v0.1 is a narrow, focused tool. It does not:

• Write to any memory surfaces
• Stage or prepare files for promotion
• Run acceptance tests against memory content
• Create snapshots or handle file promotion
• Provide a dashboard or web UI

v0.1 checks health. It does not do those things.

Installation

# Build from source
cd memory-ops
npm install
npm run build

# Run directly
node dist/index.js doctor
# or link it
npm link
memops doctor

Requires Node.js 18+ and a POSIX system.

Quick Start

# Generate a starter config
memops init

# Edit memops.yaml to match your workspace layout
# then run the doctor
memops doctor

Commands

memops init

Generates a starter memops.yaml in the current directory.

memops init           # fails if memops.yaml already exists
memops init --force   # overwrites existing config

memops doctor

Runs all 8 integrity checks and reports results.

memops doctor                  # human-readable output
memops doctor --json           # JSON output
memops doctor --quiet          # summary only
memops doctor --fail-on-warn   # exit 2 on any warning
memops doctor --config /path/to/memops.yaml

Exit codes: | Code | Meaning | |------|---------| | 0 | All checks passed | | 1 | Any warning (no failures) | | 2 | Any failure | | 3 | Config error |

Example output:

=== memops doctor ===
Workspace: /home/user/workspace
Adapter:   null

Checks:
  [PASS] canonical-files      - All 2 configured surfaces present
  [N/A]  index-freshness      - Skipped — null adapter has no index
  [PASS] symlink-detection    - No dangerous symlinks detected
  [PASS] local-first-path     - All paths appear to be on local filesystem
  [PASS] permissions          - Permissions OK
  [N/A]  retrieval-smoke      - Skipped — no adapter configured
  [PASS] weekly-recency       - Weekly summary recent (3d old)
  [N/A]  index-dirty          - Skipped — null adapter has no dirty flag

Summary: 5 PASS, 0 WARN, 0 FAIL, 3 N/A
Status:  PASS

memops status

Short-form health summary, suitable for shell prompts or CI badges.

memops status         # one-line summary
memops status --json  # JSON summary

Example output:

memops: PASS | 5P 0W 0F 3N/A | /home/user/workspace

Configuration

memops looks for memops.yaml in the current working directory by default. Use --config to override.

memops doctor --config /path/to/custom-config.yaml

See memops.yaml.example for all options.

Minimal config:

workspace: /path/to/workspace

Full config:

workspace: /path/to/workspace
adapter: null  # or "openclaw"

memory:
  surfaces:
    - path: memory/MEMORY.md
      role: durable     # critical — FAIL if missing
    - path: memory/active-projects.md
      role: working     # non-critical — WARN if missing
  weeklyDir: memory/weekly

checks:
  retrieval:
    query: "memory"
    expectSource: "memory"

The 8 Checks

| Check | What it verifies | |-------|-----------------| | canonical-files | Configured memory surfaces exist on disk | | index-freshness | Memory index was updated within the last 24h | | symlink-detection | No dangerous symlinks in the workspace tree | | local-first-path | Memory surfaces are on a local filesystem | | permissions | Memory files are not world-readable/writable | | retrieval-smoke | Retrieval returns results for the configured query | | weekly-recency | A weekly summary exists and is under 7 days old | | index-dirty | The index dirty flag is not set |

Checks requiring an adapter (index-freshness, retrieval-smoke, index-dirty) report as [N/A] when using the null adapter.

Adapters

Null adapter (default)

Runs all filesystem-based checks. No external CLI required. Retrieval checks are skipped.

adapter: null

OpenClaw adapter

Integrates with the OpenClaw CLI for retrieval smoke tests and index status.

adapter: openclaw

Requires openclaw to be on PATH. Uses:

• openclaw memory status --json
• openclaw memory search "<query>"

If the OpenClaw CLI is unavailable or returns an error, adapter-backed checks fail with a clear error message. They do not pass silently.

Running Tests

npm install
npm test

Tests are fixture-based and do not require a live OpenClaw install.

Design Principles

• Read-only. memops never writes to production memory surfaces.
• Local-first. Works entirely on the local filesystem.
• Explicit config. No magic path conventions. You define your surfaces.
• Narrow scope. memops checks health. It does not manage, improve, or modify memory.

License

MIT