odd-memory

Persist, recall, and show committed observability memory artifacts under .odd/ in git repositories.

9|2|Updated Aug 16, 2026
One-click install
npx skills add https://github.com/using-system/oddyssey --skill odd-memory-using-system
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: odd-memory
Source: https://github.com/using-system/oddyssey/tree/main/.apm/skills/odd-memory
Command: npx skills add https://github.com/using-system/oddyssey --skill odd-memory-using-system

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Observability-driven development runs lose their findings between sessions because reports, benchmarks, and maintainer decisions have no committed home, forcing every new run to start blind. This Skill defines the contract for a git-committed memory under .odd/ so reports, benchmarks, custom stacks, and rulings are versioned, reviewable, and recallable. ## Core Features & Use Cases - Memory contract for five artifact kinds: observation reports, instrumentation reports, maintainer-ruling ledgers, k6 benchmarks, and custom observability stacks, each with its own reference file defining paths, frontmatter, recall matching, and commit discipline. - Scripted recall and ledger writes: scripts/odd_recall.py filters stored frontmatter by service, stack, and environment without loading prose into context, and scripts/odd_ledger.py validates and appends finding decisions and tree-entry classifications. - Append-only evidence with living-source exceptions: reports and ledgers are never rewritten, while benchmarks and custom stacks update through reviewed diffs, with work-branch and lone-commit rules enforced. - Use Case: After an observation run finds a latency regression, persist the report to .odd/observe-run-reports/, record a wontfix decision on one finding via the ledger script, and recall the baseline before the next verification run. ## Quick Start Ask the agent to recall the previous observation reports for a service and stack using the odd-memory recall script before starting a new observability run.

Frequently Asked Questions about odd-memory

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I persist an observation run report in a git repository?

Observation reports are stored under .odd/observe-run-reports/ with a UTC-timestamped filename and YAML frontmatter mirroring the run as executed. The odd_report.py script handles naming, checks, and committing the file alone on a docs/odd-observe-run-report work branch.

How do I recall a baseline report before a new observability run?

Run scripts/odd_recall.py with --repo, --service, --stack, and --env flags to list matching stored frontmatter newest first without loading report bodies. The first line is the baseline, which you then read by section rather than whole.

How do I record a wontfix decision on a finding?

Use scripts/odd_ledger.py with the decide subcommand, passing the report filename, finding ID, verdict, and a one-sentence rationale. The script validates the finding exists in the stored report, refuses secrets in the rationale, and appends one row to .odd/decisions.md.

Can stored observation reports be edited after a run?

No, reports and ruling ledgers are append-only evidence; a new run writes a new file and decisions are new rows, with the latest row winning. Only benchmarks and custom stacks are living source, updated in place through reviewed diffs.

What are the limitations of the odd-memory recall script?

The recall script only matches on services, stack, environment, mode, and project from frontmatter; it does not rank or summarize report content. A missing or empty store is reported as a first run, and unreadable frontmatter is flagged on stderr rather than skipped silently.