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.

Antivirus / Distribution notes

Self-signed PyInstaller binaries trigger heuristic flags on Defender, Surfshark, Avira, and a few others on the first run. The signed release is technically valid (Authenticode verifies; SHA-256 matches the GitHub Release manifest), but the cert is not from a paid CA, so fresh installs often see the EXE quarantined.

Three avoidance paths, in order of friction:

1. Use the source-mode pip install (recommended for OSS adopters). A pure-Python package never triggers PE heuristics — pip wheels are not scanned the way EXEs are. The autostart hooks the package writes target pythonw.exe -m memoria, so login auto-launch works the same as the EXE without ever invoking a PE bundler.

2. Trust the Memoria cert at machine level (one-time, no money). After the first AV quarantine, run an elevated PowerShell once:

$cert = Get-ChildItem Cert:\CurrentUser\My |
    Where-Object { $_.Subject -like '*Memoria*' } | Select-Object -First 1
foreach ($store in 'Root','TrustedPublisher') {
    $s = New-Object System.Security.Cryptography.X509Certificates.X509Store($store, 'LocalMachine')
    $s.Open('ReadWrite'); $s.Add($cert); $s.Close()
}
Add-MpPreference -ExclusionPath  "$env:LOCALAPPDATA\Memoria"
Add-MpPreference -ExclusionProcess 'Memoria.exe'
Add-MpPreference -ExclusionProcess 'Memoria-cli.exe'
& 'C:\Program Files\Windows Defender\MpCmdRun.exe' -Restore -Name Memoria.exe

After this, every Memoria EXE signed by the same cert (across all future updates) is trusted by Defender + the OS shell. No further prompts.

3. Submit SHA-256 to AV vendor whitelists (free, 2-7 days). Defender, Avira, Surfshark, Avast, BitDefender, Kaspersky, and Trend Micro all accept false-positive submissions. Forking maintainers should re-submit each release's SHA-256 — once approved the EXE is permanently whitelisted upstream for every user. We do this for the canonical Memoria release; downstream forks need to re-submit their own SHAs.

The pip route (path 1) is the recommended distribution channel for the OSS ecosystem precisely because it sidesteps all three AV surfaces. The EXE route is a convenience for users who don't want to install Python.

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