concinno-skills-memoria 0.3.1

Memoria — Windows memory hygiene tray + headless cleanup CLI for agents. Concinno's user-facing memory module.

concinno-skills-memoria

Windows memory hygiene tray — RAM cleanup, scheduler, process whitelist, foreground-window exclusion, and headless CLI for agent integration.

Memoria is the user-facing application layer over Concinno's memory_relief and process_guard Win32 primitives. This sub-package ships Memoria as a standard pip-installable Python source package, plus an opt-in installer that fetches the pre-built signed Memoria.exe from a GitHub Release.

Install

Source mode (cross-platform, ~50 KB wheel)

pip install concinno-skills-memoria
python -m memoria          # tray app on Windows; CLI on Linux/Mac

The source-mode entry works on every platform Python supports. On Windows it brings up the system-tray + GUI; on Linux/Mac the GUI features no-op gracefully and only the CLI subcommands are useful.

Standalone EXE (Windows-only, ~94 MB bundle)

After installing the pip package, fetch the signed binary:

memoria-install-exe

This downloads the GitHub Release zip, verifies SHA-256, extracts to %LOCALAPPDATA%\Memoria\, and creates a Start Menu shortcut. Then Memoria.exe is available system-wide.

Set MEMORIA_RELEASE_URL env var to override the upstream release URL for forks / private deployments.

Headless CLI for agents

# Print one memory snapshot as JSON
memoria --snap --compact

# Run a SAFE-tier cleanup, agent-style (no history pollution, quiet)
memoria --tier=safe --json --no-history --compact --quiet

# Force-trim the foreground app too (useful for benchmarking)
memoria --tier=safe --no-exclude-foreground

# Standalone EXE works the same way
Memoria.exe --tier=safe --json

JSON schema_version 1.0 contract (top-level fields):

{
  "schema_version": "1.0",
  "when": "...",
  "mode": "safe",
  "before": {"used_pct": ..., "available_gb": ..., ...},
  "after":  {"used_pct": ..., ...},
  "freed_mb": 512,
  "process_guard_run": false,
  "history_persisted": false,
  "exit_status": "ok",
  "report": {
    "reclaimed_mb": 512, "elapsed_ms": 1234,
    "is_admin": false, "foreground_excluded": "chrome.exe",
    "stages": [...], "process_trims": [...], "notes": []
  }
}

Exit codes: 0 success / 1 partial (≥1 stage errored) / 2 failure (engine raised) / 3 invalid args.

Foreground window exclusion

By default Memoria spares the foreground window's process from per- process trim. Reasoning: a working-set trim costs the trimmed process 1-3 s of page-fault refill on the next mouse move, which is invisible on backgrounded apps but jarring on whatever the user is actively typing in / playing.

Toggle via --exclude-foreground / --no-exclude-foreground on the CLI, or set state.exclude_foreground_enabled (persisted in ~/.memoria/state.json).

Limitation: image-name granularity. If chrome.exe is foreground, every Chrome process is spared, not just the visible PID. PID-tree exclusion needs concinno.memory_relief.engine.run_cleanup to accept an exclude_pids: frozenset[int] argument — staged for a future concinno release.

Build the EXE locally

pip install concinno-skills-memoria[build]
# Then from a checkout that contains memoria.spec + memoria_launch.py:
pyinstaller --noconfirm memoria.spec

The bundled PyInstaller spec produces an onedir bundle (loader + _internal/) that Surfshark / Avira no longer flag as suspicious (historically --onefile triggered self-extract heuristics — see project handoff for forensic details).

For signed distribution: the included build_signed_exe.ps1 (in the parent scripts/ directory of the canonical workspace) handles build + Authenticode self-sign + verify in one shot. Bring your own cert with subject CN=AI King — Memoria (or pass -CertSubject to the script).

Source-of-truth

The canonical Memoria source currently lives at ~/.claude/scripts/memoria/ in the AI King workspace. Files under src/memoria/ in this package are a copy synced for distribution.

Sync direction: scripts/memoria/ → src/memoria/. To regenerate from the canonical workspace::

# From the workspace root
Copy-Item -Force -Recurse `
    "$env:USERPROFILE\.claude\scripts\memoria\*.py" `
    "projects\concinno-skills-memoria\src\memoria\"

A future migration consolidates source canonically into src/memoria/ and turns ~/.claude/scripts/memoria/ into a junction or re-export shim. Tracked in the parent project handoff.

License

AGPL-3.0-or-later. See LICENSE — same license as Concinno.

Links

• Concinno (parent): https://pypi.org/project/concinno/
• Source: https://github.com/aiking931931/concinno
• Issues: https://github.com/aiking931931/concinno/issues