Metadata-Version: 2.4
Name: mimir-governed-memory
Version: 0.1.1
Summary: Governed autonomous memory brain for agents
Author: nichkolasrepo
License-Expression: MIT
Project-URL: Repository, https://github.com/nichkolasrepo/mimir
Project-URL: Issues, https://github.com/nichkolasrepo/mimir/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "postgres"
Dynamic: license-file

# Mimir

Mimir is a governed autonomous memory brain for agents.

It helps agents remember what matters, retrieve the right memory at the right time, propose better memory, and improve future behavior without silently rewriting truth. The v1 roadmap adds deterministic stale-knowledge checks and broader drift detection.

The product center is the memory contract:

```txt
agent / harness / adapter -> Mimir -> memory + evidence + status + retrieval + review
```

The CLI is an admin/debug/migration surface, not the primary product interface.

Mimir is intended to run on both macOS and Windows. Examples below use PowerShell where environment variables differ; macOS shells use `export NAME=value` and POSIX-style paths.

Current backing modes:

- workspace mode: Markdown memory in `mimir/` and SQLite state in `.mimir/mimir.db`
- agent-home mode: Markdown memory in `$MIMIR_HOME/memory/` and SQLite state in `$MIMIR_HOME/mimir.db`
- remote/shared mode: `MimirClient` connects to a compatible service through `RemoteTransport`

Memory lifecycle events are appended to `queue/pending-events.jsonl` for idempotent replay, audit, and future sync.

This repository currently contains:

- a Python SDK/provider core
- Odin/Hermes provider entrypoints
- OpenClaw-compatible MCP bridge
- reference `mimir-service` HTTP runtime
- CLI wrappers for admin/debug/migration

The selected Python distribution name is `mimir-governed-memory`. To avoid overwriting the unrelated public `mimir-cli` project, the import package is `mimir_governed_memory` and the primary command is `mimir-governed-memory`; `mimir-mcp` and `mimir-service` remain unchanged. Version `0.1.0` is available on [TestPyPI](https://test.pypi.org/project/mimir-governed-memory/) as immutable registry-control evidence and must not be promoted because its embedded project description predates that upload. Source is versioned for the `0.1.1` candidate; TestPyPI is its non-production rehearsal index, and the repository release handoff records the current registry and exact-artifact verification state.

SDK example:

```python
from mimir_governed_memory import MemoryScope, MimirClient, RememberRequest, RetrieveRequest, StorageConfig

scope = MemoryScope(user_id="user-1", workspace_id="odin", agent_id="my-agent")
storage = StorageConfig.agent_home("~/.mimir-agent", domain_profile="builder")
client = MimirClient(storage=storage, scope=scope)
client.initialize()

pending = client.remember_request(RememberRequest(
    entry_id="user.prefers.concise.plans",
    tag="F",
    claim="User prefers concise plans.",
    evidence="human:owner@2026-07-09",
    scope=scope,
))

context = client.retrieve_request(RetrieveRequest("planning preferences", scope=scope))
```

CLI wrapper examples:

PowerShell:

```powershell
$env:PYTHONPATH='src'
python -m mimir_governed_memory.cli init --json
python -m mimir_governed_memory.cli db build --json
python -m mimir_governed_memory.cli check --json
python -m mimir_governed_memory.cli governance report --json
python -m mimir_governed_memory.cli governance report --fresh-check --json
python -m mimir_governed_memory.cli governance report --fail-on-blocked --json
python -m mimir_governed_memory.cli governance propose-improvements --fresh-check --json
python -m mimir_governed_memory.cli query "auth provider" --json
python -m mimir_governed_memory.cli archive user.prefers.concise.plans --reason stale --json
python -m mimir_governed_memory.cli doctor --json
python -m mimir_governed_memory.cli events list --json
```

macOS/Linux shell:

```bash
export PYTHONPATH=src
python -m mimir_governed_memory.cli init --json
python -m mimir_governed_memory.cli doctor --json
```

Agent-home mode:

PowerShell:

```powershell
$env:PYTHONPATH='src'
python -m mimir_governed_memory.cli --home $env:HERMES_HOME\mimir init --json
python -m mimir_governed_memory.cli --home $env:HERMES_HOME\mimir import hermes-memory --source $env:HERMES_HOME --json
python -m mimir_governed_memory.cli --home $env:HERMES_HOME\mimir review list --json
```

macOS/Linux shell:

```bash
export PYTHONPATH=src
python -m mimir_governed_memory.cli --home "$HERMES_HOME/mimir" init --json
python -m mimir_governed_memory.cli --home "$HERMES_HOME/mimir" import hermes-memory --source "$HERMES_HOME" --json
python -m mimir_governed_memory.cli --home "$HERMES_HOME/mimir" review list --json
```

OpenClaw-style imports:

PowerShell:

```powershell
$env:PYTHONPATH='src'
python -m mimir_governed_memory.cli --home $env:MIMIR_HOME import openclaw-memory --source $HOME\.openclaw --json
```

macOS/Linux shell:

```bash
export PYTHONPATH=src
python -m mimir_governed_memory.cli --home "$MIMIR_HOME" import openclaw-memory --source "$HOME/.openclaw" --json
```

After an editable install, the console script is also available:

```powershell
python -m pip install -e .
mimir-governed-memory doctor --json
mimir-mcp --help
```

The exact `0.1.0` registry-control artifact can be inspected without dependency fallback because the base package has no runtime dependencies:

```powershell
python -m pip install --no-cache-dir --index-url https://test.pypi.org/simple/ --no-deps mimir-governed-memory==0.1.0
```

Reference remote service:

```powershell
$env:MIMIR_SERVICE_HOME="$HOME\.mimir-service"
$env:MIMIR_SERVICE_API_KEY="dev-secret"
mimir-service --host 127.0.0.1 --port 8765
```

For shared deployments, `mimir-service --config <json>` supports operation-scoped API keys and JSONL request audit logs.

The hosted-authority path packages a PostgreSQL 18+ JSONB/RLS schema, checksum-verified migration runner, scoped repository adapter, terminal reviewed-lifecycle transitions, deterministic full-text retrieval/explanations, and durable database audit records. Local/workspace deployments expose a snapshot governance report plus review-gated improvement proposals: unsupported task claims become pending unknowns, and invalid policy files can become pending safe-default repairs. Neither path auto-approves or applies truth. Pass `--fresh-check` to rebuild derived checker state first; dated human/URL evidence can be checked through the opt-in `checker.stale_evidence_days` policy. Hosted request auditing fails closed with `postgres_audit_failed` if its database insert cannot persist. Unsupported hosted operations still fail closed without falling back to local storage. Local service behavior is unchanged. See [docs/hosted-postgres.md](docs/hosted-postgres.md) for configuration, supported operations, and migration details.

Release verification:

```powershell
python scripts/release_verify.py
python scripts/release_verify.py --build-wheel
python scripts/release_verify.py --build-wheel --require-postgres
```

The release verifier writes `dist/release-manifest.json` with versions, wheel hash, SDK exports, console scripts, verification commands, and an explicit live-PostgreSQL acceptance result. When `MIMIR_TEST_POSTGRES_DSN` is configured, the verifier passes it only to the focused hosted lifecycle integration suite and records `passed` without storing the DSN value. Source discovery, builds, installs, and console probes run with that credential removed from their child environments. Without the environment variable the manifest records `skipped`; `--require-postgres` instead fails closed. The verifier checks local install readiness but does not publish.

Native Hermes/Odin integration imports `mimir_governed_memory.agent_provider.MimirMemoryProvider`. OpenClaw and other MCP-capable agents can use `mimir-mcp` as a stdio MCP bridge.

See [docs/launch.md](docs/launch.md) for the end-to-end launch path across SDK harnesses, remote/shared service mode, Odin, Hermes, OpenClaw MCP, imports, review/apply, and recovery.
See [docs/release-handoff.md](docs/release-handoff.md) for the current candidate gate, wheel hash, SDK exports, and remaining release decisions.

## License

Mimir is licensed under the [MIT License](LICENSE).
