Memory check-up

A one-command health report on your agent's memory. Surfaces duplicates, stale entries, things near the storage cap, and anything that looks structurally off. Useful weekly. Essential before a big launch. Paid-tier feature.

The idea, in plain language

Just like your code can benefit from a linter (a program that points out small problems before they become bugs), your agent's memory can drift over time. Duplicates creep in. Stale facts pile up. The agent might be hanging on to flagged actors you've forgotten about. The memory check-up reads through everything and tells you what looks wrong.

What you see when you run it

A clean health report, like this:

╔══════════════════════════════════════════════════════════════════╗
║                  SIBYL MEMORY · LINT REPORT                       ║
╠══════════════════════════════════════════════════════════════════╣
║  tenant       │ [email protected]                                 ║
║  db path      │ memory.db                                         ║
║  schema v     │ 2                                                 ║
║  db size      │ 1247.8 KB                                         ║
╠══════════════════════════════════════════════════════════════════╣
║  entities          │ 142                                          ║
║  journal_events    │ 1840                                         ║
║  reference_documents │ 23                                         ║
║  archived_entities │ 18                                           ║
║  skill_proposals   │ 9                                            ║
╠══════════════════════════════════════════════════════════════════╣
║  [⚠ warning] db-soft-cap                                          ║
║    local DB is at 82.1% of the 2 MB cap                           ║
║    → Archive stale entities or upgrade to remove the cap.         ║
║                                                                   ║
║  [⚠ warning] duplicate-entity                                     ║
║    entity name 'atlas' appears in 2 categories                    ║
║    → Pick one canonical category and archive the other.           ║
║                                                                   ║
║  [i info] stale-entity                                            ║
║    entity person/old-collaborator hasn't been updated since       ║
║    2025-10-01T00:00:00Z (> 90 days)                              ║
║    → Update or archive.                                           ║
╠══════════════════════════════════════════════════════════════════╣
║  0 critical · 2 warnings · 1 info                                  ║
╚══════════════════════════════════════════════════════════════════╝

What it checks

Eleven checks across three severity levels.

Three severity levels, three different reactions

Critical (red)

Something is structurally broken. The schema is out of date, or a row that should be valid JSON isn't. The agent might still work, but it's working on borrowed time. Fix critical issues before doing anything else.

Warning (amber)

Something is messy. Duplicates, near-cap, search index drift. Won't break anything immediately but degrades the agent's quality. Schedule a clean-up.

Info (grey)

FYI items. Stale entries, empty journal events, recent flags worth a re-read. Read through these once a week to keep the agent's worldview tidy.

How to run it (when you're on a paid tier)

In Python:

report = memory.lint()
print(report.to_ascii())

Once the sibyl terminal command ships, the friendlier version is:

sibyl lint

Programmatic access for automation:

report = memory.lint()
if not report.ok:
    print("memory needs attention")
    for finding in report.critical:
        print(f"  - {finding.check}: {finding.message}")

When to run it

• Weekly, as a routine. A 5-second scan catches drift before it accumulates.
• Before a big launch. Confirm the agent's worldview matches yours before shipping.
• After an unusual session. If the agent did something surprising, the check-up can show whether something in memory caused it.
• Whenever you upgrade between Sibyl Memory Plugin versions. Catches anything the migration didn't.

Once the sibyl terminal command ships, the install will offer to schedule a daily check-up via your system's task scheduler (cron on Mac/Linux, Task Scheduler on Windows). You'll get a one-line summary in your morning terminal output. Opt-in, of course.

Why this is a paid-tier feature

The memory check-up is the diagnostic layer. If self-learning is "make the agent smarter," the check-up is "keep the agent honest." Both compound. Neither matters much in the first day; both matter a lot by month three. Both are reserved for users who care enough to pay for them.