Metadata-Version: 2.4
Name: concinno-skills-memoria
Version: 0.5.0
Summary: Memoria — Windows memory hygiene tray + headless cleanup CLI for agents. Concinno's user-facing memory module.
Project-URL: Homepage, https://github.com/aiking931931/concinno
Project-URL: Documentation, https://github.com/aiking931931/concinno/blob/main/projects/concinno-skills-memoria/README.md
Project-URL: Repository, https://github.com/aiking931931/concinno
Project-URL: Issues, https://github.com/aiking931931/concinno/issues
Project-URL: Changelog, https://github.com/aiking931931/concinno/blob/main/projects/concinno-skills-memoria/CHANGELOG.md
Author-email: "AI King (Chen-Xuan Wang)" <me@ai-king.dev>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: agent,cleanup,concinno,memoria,memory,performance,ram,tray,windows
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: concinno>=4.4.0
Requires-Dist: customtkinter>=5.2
Requires-Dist: pillow>=10
Requires-Dist: psutil>=5.9
Requires-Dist: pystray>=0.19
Requires-Dist: pywin32>=306; sys_platform == 'win32'
Requires-Dist: windows-toasts>=1.3; sys_platform == 'win32'
Provides-Extra: build
Requires-Dist: pillow>=10; extra == 'build'
Requires-Dist: pyinstaller>=6.0; extra == 'build'
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# 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)

```bash
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:

```bash
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:

```powershell
$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

```bash
# 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):

```json
{
  "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

```bash
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::

```powershell
# 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](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>
