Skip to content

LeoYeAI/agent-master-skills / skills/agent-memory-system-guide

Agent Memory System Guide

Verified

An agent memory workflow guide for OpenClaw and Codex with MEMORY.md, daily notes, SESSION-STATE, working-buffer, Obsidian archiving, and optional OpenViking support.

FileKindSize
INSTALL.mdmarkdown1.1 KB
README.mdmarkdown12.4 KB
README_CN.mdmarkdown11.6 KB
README_EN.mdmarkdown12.3 KB
SKILL.mdskill md18.8 KB
_meta.jsonconfig833 B
docs/superpowers/plans/2026-03-21-agent-memory-system-guide-obsidian-native.mdmarkdown5.3 KB
docs/superpowers/plans/2026-03-25-memory-backup-import-export.mdmarkdown3.9 KB
docs/superpowers/plans/2026-03-25-memory-examples-maintenance.mdmarkdown3.2 KB
docs/superpowers/plans/2026-03-25-report-warning-example.mdmarkdown1.9 KB
docs/superpowers/plans/2026-03-26-import-clean-mode.mdmarkdown8.6 KB
docs/superpowers/plans/2026-03-26-metadata-bootstrap-safety.mdmarkdown5.4 KB
docs/superpowers/plans/2026-03-27-memory-positioning.mdmarkdown2.6 KB
docs/superpowers/plans/2026-03-27-report-json.mdmarkdown5.5 KB
docs/superpowers/specs/2026-03-21-agent-memory-system-guide-obsidian-design.mdmarkdown5.1 KB
docs/superpowers/specs/2026-03-25-memory-backup-import-export-design.mdmarkdown3.1 KB
docs/superpowers/specs/2026-03-25-memory-examples-maintenance-design.mdmarkdown2.8 KB
docs/superpowers/specs/2026-03-26-import-clean-mode-design.mdmarkdown5.6 KB
docs/superpowers/specs/2026-03-26-metadata-bootstrap-safety-design.mdmarkdown5.0 KB
docs/superpowers/specs/2026-03-27-memory-positioning-design.mdmarkdown4.4 KB
docs/superpowers/specs/2026-03-27-report-json-design.mdmarkdown4.0 KB
manifest.tomlconfig944 B
scripts/memory_capture.pyscript17.3 KB
templates/OBSIDIAN-NOTE.mdmarkdown530 B
templates/SESSION-STATE.mdmarkdown137 B
templates/memory-capture.mdmarkdown385 B
templates/working-buffer.mdmarkdown105 B
tests/test_gitignore_publish_artifacts.pyscript514 B
tests/test_install_contract.pyscript384 B
tests/test_memory_capture_contract.pyscript6.9 KB
tests/test_memory_capture_script.pyscript16.8 KB
tests/test_memory_recovery_contract.pyscript1.5 KB
tests/test_obsidian_contract.pyscript503 B
tests/test_obsidian_template_contract.pyscript183 B
tests/test_openclaw_memory_search_contract.pyscript366 B
tests/test_openviking_optional_contract.pyscript371 B
tests/test_readme_openviking_optional.pyscript383 B
tests/test_release_manifest_contract.pyscript1.3 KB
tests/test_skill_positioning_contract.pyscript849 B

docs/superpowers/specs/2026-03-27-report-json-design.md

View on GitHub
# Report JSON Output Design

## Scope

This design adds a machine-readable `--json` mode to the `report` subcommand in `scripts/memory_capture.py`.

The change is intentionally narrow:

- Only `report` gains JSON stdout output.
- Existing human-readable stdout output remains the default.
- Existing Markdown file output through `--output` remains unchanged.

This iteration does not add `--json` to `bootstrap`, `export`, or `import`, and does not introduce `--dry-run`.

## Goals

- Make `report` easy to consume from automation, scripts, and other skills.
- Preserve current CLI behavior for existing users.
- Reuse the existing `ReportData` shape instead of inventing a second reporting model.

## Non-Goals

- Add JSON output to every subcommand.
- Replace Markdown report generation.
- Add dry-run planning or command tracing.
- Change report semantics or warning rules.

## Current Behavior

`report` currently:

1. Validates that the workspace exists.
2. Collects `ReportData`.
3. Prints a human-readable text report to stdout.
4. Optionally writes a Markdown report file through `--output`.

This works well for humans but is awkward for automation that needs stable field access.

## Options Considered

### Option 1: Add `report --json` and keep Markdown file output unchanged

Stdout becomes JSON only when `--json` is passed. `--output` still writes Markdown.

Pros:

- Smallest change with the highest immediate integration value.
- Backward compatible for existing human-oriented usage.
- Easy to test because it maps directly to `ReportData`.

Cons:

- Different output formats remain split between stdout and file output.

### Option 2: Make `--output` format-sensitive

Allow `--json` to affect both stdout and file output.

Pros:

- More uniform format behavior.

Cons:

- Expands scope and introduces ambiguity around whether `--output` should write JSON or Markdown.

### Option 3: Add a separate `report-json` subcommand

Pros:

- Explicit command naming.

Cons:

- Worse CLI ergonomics and unnecessary surface area.

## Recommended Design

Adopt Option 1.

### CLI

Add a new boolean flag to `report`:

- `--json`: print the report payload as JSON to stdout.

Behavior:

- `report` with no flag: current human-readable stdout output.
- `report --json`: JSON stdout.
- `report --output file.md`: current text stdout plus Markdown file.
- `report --json --output file.md`: JSON stdout plus Markdown file.

## Data Shape

The JSON payload should reflect `ReportData` closely:

```json
{
  "workspace": "/abs/path",
  "supported_files": {
    "MEMORY.md": true,
    "SESSION-STATE.md": false,
    "working-buffer.md": true,
    "memory-capture.md": true
  },
  "memory_note_count": 2,
  "attachments_count": 1,
  "latest_daily_note": "memory/2026-03-25.md",
  "warnings": [
    "Missing supported file: SESSION-STATE.md"
  ]
}
```

Field rules:

- `workspace`: absolute path string
- `supported_files`: filename to boolean presence map
- `memory_note_count`: integer
- `attachments_count`: integer
- `latest_daily_note`: relative path string or `null`
- `warnings`: list of strings

## Implementation Notes

- Add a serializer helper for `ReportData` rather than building JSON inline in `handle_report()`.
- Reuse the existing relative-path logic for `latest_daily_note`.
- Use `json.dumps(..., ensure_ascii=False, indent=2)` for readable machine output.
- Keep Markdown output logic unchanged.

## Testing Strategy

Add focused tests for:

1. `report --json` returns valid JSON with the expected fields.
2. `latest_daily_note` is serialized as a relative path or `null`.
3. `report --json --output file.md` still writes the Markdown report file.

Then run the full pytest suite to catch regressions.

## Files Expected To Change

- `scripts/memory_capture.py`
- `tests/test_memory_capture_script.py`

## Acceptance Criteria

- `report --json` prints valid JSON to stdout.
- The JSON fields match the existing report semantics.
- `--output` continues to write Markdown, even when `--json` is used.
- Human-readable `report` behavior remains unchanged by default.
- Full pytest suite passes.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall