# https://github.com/nousergon/mnemon Project Manual

Generated at: 2026-07-18 21:22:31 UTC

## Table of Contents

- [Overview & System Architecture](#page-1)
- [Core Features: MCP Tools, Memory Types, and Claude Code Hooks](#page-2)
- [Data Management, Search, and Intelligence Subsystems](#page-3)
- [Deployment, Operations, and Multi-Client Integration](#page-4)

<a id='page-1'></a>

## Overview & System Architecture

### Related Pages

Related topics: [Core Features: MCP Tools, Memory Types, and Claude Code Hooks](#page-2), [Data Management, Search, and Intelligence Subsystems](#page-3), [Deployment, Operations, and Multi-Client Integration](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/nousergon/mnemon/blob/main/README.md)
- [pyproject.toml](https://github.com/nousergon/mnemon/blob/main/pyproject.toml)
- [ARCHITECTURE.md](https://github.com/nousergon/mnemon/blob/main/ARCHITECTURE.md)
- [src/mnemon/__init__.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/__init__.py)
- [src/mnemon/__main__.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/__main__.py)
- [src/mnemon/server.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/server.py)
- [src/mnemon/cli.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/cli.py)
- [src/mnemon/memory_save.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/memory_save.py)
- [src/mnemon/mirror.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/mirror.py)
- [src/mnemon/calibration.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/calibration.py)
- [src/mnemon/decay.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/decay.py)
- [.github/workflows/ci.yml](https://github.com/nousergon/mnemon/blob/main/.github/workflows/ci.yml)
</details>

# Overview & System Architecture

## Purpose & Scope

mnemon is a persistence and handoff store designed for AI coding and chat sessions. Its role is to capture decisions, framings, and operating context produced inside interactive AI tools and recall them across sessions and surfaces. The package is published to PyPI as `mnemon-memory`, with the CLI binary exposed as `mnemon`. Source: [pyproject.toml:1-40]()

The system is surface-agnostic on purpose: it is meant to serve Claude Code hooks, the claude.ai chat surface, ad-hoc CLI users, and MCP clients through one shared substrate. Operationally it runs as a long-lived service hosted on Fly.io, and is also installable for local SQLite-only use. Source: [README.md:1-80]()

The current stable line is `0.7.x`, with `v0.7.7` as the latest release introducing prose supersession auto-detect in `memory_save`. Source: [releases/v0.7.7:1-30]()

## High-Level Components

The repository is laid out as a small Python package plus a thin server entrypoint. The following components recur throughout the codebase and the issue tracker.

| Layer | Module | Role |
|-------|--------|------|
| Public CLI | `src/mnemon/cli.py` | `mnemon`, `mnemon uninstall`, calibration subcommands |
| MCP server | `src/mnemon/server.py` | Stamps `source_client` from MCP `clientInfo`, exposes tools |
| Capture substrate | `src/mnemon/memory_save.py` | Persists documents and relations; auto-detects `supersedes id N` |
| Salience tier | Phase 2/3 of capture-attention | Standing-tier feature (`MNEMON_STANDING_TIER_ENABLED`) |
| Decay | `src/mnemon/decay.py` | Wall-clock confidence-decay sweep (#218) |
| Mirror | `src/mnemon/mirror.py` | Cross-device replication; sets `source_client=mnemon-mirror` |
| Calibration | `src/mnemon/calibration.py` | Operator tooling; `--use-fixture` reads `.json` or `.example.json` |

Source: [ARCHITECTURE.md:1-60](), [src/mnemon/server.py:1-40](), [src/mnemon/cli.py:1-40]()

Capture-attention is phased. Phase A activation infrastructure is gated by `MNEMON_CAPTURE_ATTENTION_ENABLED`, mirroring the standing-tier pattern so operators can flip it via `flyctl secrets set` without redeploying. Phases B and C consolidate substrate work and remain default-off pending a re-soak gate. Source: [releases/v0.7.0rc4:1-40](), [releases/v0.7.0rc6:1-40]()

## Data Flow & Save Semantics

A save enters through one of three surfaces: a Claude Code hook, the MCP server, or the CLI. The `memory_save` tool accepts a document plus optional `correction_of` and relation metadata. When `correction_of` is omitted but the body explicitly states it supersedes a specific id (e.g. `supersedes id N`, `#N`, or natural-language variants), the `'supersedes'` relation is recorded automatically and a WARN is emitted rather than failing silently. Source: [src/mnemon/memory_save.py:1-120](), [releases/v0.7.7:1-30]()

Provenance is stored on `documents.source_client`. Today that field is populated only when the caller passes it — hooks pass `claude-code-hook`, the mirror passes `mnemon-mirror`, and the CLI passes its own identifier. Issue #274 notes that explicit MCP saves are currently surface-indistinguishable (NULL provenance) because the server does not yet stamp `clientInfo` server-side. Source: [issue #274](), [src/mnemon/server.py:40-90]()

A practical consequence noted in issue #273 is that the claude.ai chat surface never writes to mnemon, so an autonomous-save posture decision is still open. The intended target is a Profile snippet or explicit-only contract documented in the README. Source: [issue #273]()

## Operations, CI & Deployment

Deployment centers on Fly.io. The README documents a ~1s suspend–resume budget, improved by the `stop`→`suspend` change in #213, and the calibration command has its own fixture-fallback concern: `--use-fixture` reads a `.json` that is not present on a fresh clone, so a `.json`→`.example.json` fallback is tracked in issue #236. Source: [README.md:80-160](), [issue #236](), [issue #246]()

CI runs on a self-hosted AL2023 runner (PR #271). The bootstrap pre-caches Python 3.12, but `ci.yml` still advertises a multi-version matrix (3.10/3.12/3.13) over `matrix.os`; issue #272 is the open follow-up to verify the matrix on the new runner before further repointing. Source: [.github/workflows/ci.yml:1-80](), [issue #272]()

Backlog discipline is handled externally. The fleet groomer (`alpha-engine-config/scripts/groom_driver.py` `BACKLOG_REPOS`) does not enumerate this repo today; issue #276 is the open decision of whether to wire mnemon in or keep it interactive-only. Pre-existing ruff debt (66 errors on `main`, mostly unused imports in tests) was missed because ruff was not on the CI path; that gap is tracked separately and is now a `good first issue`. Source: [issue #276](), [issue #263]()

The decay sweep introduced in v0.7.6 (#218) is wall-clock-based so it survives Fly machine suspension and is no longer silent — an operator running the service on a hibernating machine will see it fire correctly on resume without manual triggering. Source: [releases/v0.7.6:1-30](), [src/mnemon/decay.py:1-40]()

## Boundaries & Open Questions

Several architectural decisions remain deliberately unsettled and are visible in the issue tracker:

- **Provenance for MCP saves** — whether to stamp `source_client` server-side from `clientInfo` (#274).
- **Autonomous save posture** — claude.ai chat never persists today; the contract is undecided (#273).
- **Fleet groomer inclusion** — mnemon is interactive-only until #276 is resolved.
- **CI matrix migration** — Python 3.10/3.13 on the AL2023 self-hosted runner is unverified (#272).

These are tracked as the public backlog because the underlying mnemon-ops board was migrated into this repo on 2026-06-18, so every `area:docs` or `good first issue` label you see predates that migration. Source: [issue #236](), [issue #244](), [issue #246]()

---

<a id='page-2'></a>

## Core Features: MCP Tools, Memory Types, and Claude Code Hooks

### Related Pages

Related topics: [Overview & System Architecture](#page-1), [Data Management, Search, and Intelligence Subsystems](#page-3), [Deployment, Operations, and Multi-Client Integration](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/mnemon/api.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/api.py)
- [src/mnemon/cli.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/cli.py)
- [src/mnemon/hooks/framework.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/hooks/framework.py)
- [src/mnemon/hooks/context_surfacing.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/hooks/context_surfacing.py)
- [src/mnemon/hooks/session_extractor.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/hooks/session_extractor.py)
- [src/mnemon/hooks/handoff_generator.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/hooks/handoff_generator.py)
</details>

# Core Features: MCP Tools, Memory Types, and Claude Code Hooks

mnemon is a long-lived memory store that exposes its persistence and recall surface to AI assistants through the **Model Context Protocol (MCP)** and to human operators through a CLI. Three components form the core of the system: the MCP-exposed API, the underlying document model, and the Claude Code hook pipeline that turns live coding sessions into structured memories.

## MCP Tools Surface

The MCP server is defined in `api.py` and registers the tools that any MCP-capable client (Claude Code, Claude Desktop, mnemon-mirror, custom agents) can invoke. The tool names map directly onto the memory lifecycle: persist a memory, recall memories, and manage relations between them.

| Tool | Purpose | Notes |
|---|---|---|
| `memory_save` | Persist a new memory; auto-detects supersession when `correction_of` is omitted but the prose names a target id | Added in v0.7.7 (#219) — additive, WARNs only |
| `memory_recall` | Retrieve memories by query, id, or relation | Returns documents + relations |
| `memory_link` | Explicitly record a relation (e.g. `supersedes`, `correction_of`, `derived_from`) | Use when the auto-detector is insufficient |

Provenance is stamped through a `source_client` parameter that the *caller* supplies. The Claude Code hook pipeline always passes `claude-code-hook`, the mirror passes `mnemon-mirror`, and the CLI passes the operator identifier. Issue #274 tracks the open question of stamping `source_client` server-side from MCP `clientInfo` so that explicit saves are no longer surface-indistinguishable from NULL-provenance writes. Source: [src/mnemon/api.py:1-120]()

## Memory Types

The schema is document-centric. Each row in the `documents` table is a memory, and relations live in a separate edge table that links memory ids together. The minimum a memory needs is a body; everything else is metadata that either aids recall or traces provenance.

- **Identity**: integer `id` assigned at write time, used by all relations and by the prose-supersession detector (which scans for `supersedes id N` / `#N`). Source: [src/mnemon/api.py:120-210]()
- **Content fields**: `content` (the prose body), structured metadata for tier, confidence, salience.
- **Provenance fields**: `source_client` (caller-supplied), timestamps. NULL `source_client` is the documented gap that issue #274 targets.
- **Relations**: `supersedes`, `correction_of`, `derived_from`, etc. v0.7.7 added automatic `'supersedes'` edge detection to `memory_save` when the prose explicitly names a target id. Source: [src/mnemon/api.py:60-115]()
- **Salience tiers** (Phase 2/3, released in 0.7.0rc6): capture-attention gating is operator-explicit and default-off, with the `MNEMON_CAPTURE_ATTENTION_ENABLED` and `MNEMON_STANDING_TIER_ENABLED` env-var overrides.

Hook-pipeline saves and CLI saves share the same table; the only distinction is the `source_client` label, which is why #274 is a meaningful semantic gap and not a cosmetic one.

## Claude Code Hook Pipeline

The hook pipeline is what makes mnemon useful inside a Claude Code session. Four modules cooperate; `hooks/framework.py` is the orchestrator and the other three are stage handlers.

```mermaid
flowchart LR
    CC[Claude Code session] -->|events| F[hooks/framework.py]
    F --> E[hooks/session_extractor.py]
    E -->|candidate memories| C[hooks/context_surfacing.py]
    C -->|relevant recall| H[hooks/handoff_generator.py]
    H -->|memory_save| API[api.py]
    API --> DB[(documents + relations)]
```

- **Session extractor** (`session_extractor.py`): listens to Claude Code events and pulls candidate memories out of the live transcript — decisions, corrections, named entities. Filtered, not raw: a chat surface that never reaches mnemon (issue #273, the claude.ai chat surface) produces no hook events and therefore no candidates. Source: [src/mnemon/hooks/session_extractor.py:1-80]()
- **Context surfacing** (`context_surfacing.py`): before any save, queries the existing store for relevant prior memories and surfaces them to the orchestrator. This is what makes later saves *corrections* rather than duplicates — the supersession auto-detector can only fire if the surfacer already showed the old memory. Source: [src/mnemon/hooks/context_surfacing.py:1-90]()
- **Handoff generator** (`handoff_generator.py`): assembles the final memory payload, including the explicit `source_client = "claude-code-hook"` stamp and the relation edges the extractor surfaced. Source: [src/mnemon/hooks/handoff_generator.py:1-120]()

The framework module itself owns the stage ordering, error handling, and the decision to call `memory_save` once per emitted memory rather than once per session. Source: [src/mnemon/hooks/framework.py:1-100]()

## Operator Surface: CLI

The CLI in `cli.py` is the human-facing entry point and the only path that bypasses the hook pipeline. Its saves are stamped with the operator's identifier, not `claude-code-hook`, which means a CLI-saved memory and a hook-saved memory are visibly distinct in the store today and indistinguishable once #274 lands. The CLI also exposes `mnemon uninstall`, whose current "no mnemon registration found (or CLI errored silently)" message is open for rewording (issue #244) — a reminder that CLI wording is part of the documented contract. Source: [src/mnemon/cli.py:1-120]()

Together, the MCP tools, document/relation model, hook pipeline, and CLI form a closed loop: hooks write, tools read and write, the CLI administers, and every entry is traceable back to its surface once the open provenance issues are resolved.

---

<a id='page-3'></a>

## Data Management, Search, and Intelligence Subsystems

### Related Pages

Related topics: [Overview & System Architecture](#page-1), [Core Features: MCP Tools, Memory Types, and Claude Code Hooks](#page-2), [Deployment, Operations, and Multi-Client Integration](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/mnemon/store.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/store.py)
- [src/mnemon/search.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/search.py)
- [src/mnemon/embedder.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/embedder.py)
- [src/mnemon/vecstore.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/vecstore.py)
- [src/mnemon/mirror.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/mirror.py)
- [src/mnemon/contradiction.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/contradiction.py)
</details>

# Data Management, Search, and Intelligence Subsystems

## Purpose and Scope

mnemon's data layer is split across three cooperating tiers: a relational store for documents and their provenance, a vector store for semantic retrieval, and an intelligence layer that detects supersession and decay. Together, these subsystems turn a stream of explicit saves — from the CLI, hooks, mirror, or MCP — into queryable, self-pruning long-term memory.

The subsystem boundary is enforced by module ownership: `store.py` owns the relational write/read path for `documents` rows and their relations; `vecstore.py` and `embedder.py` own the embedding-side representation; `search.py` orchestrates cross-tier recall; and `contradiction.py` and `mirror.py` provide the intelligence and provenance plumbing that sits on top. Source: [src/mnemon/store.py:1-](); [src/mnemon/vecstore.py:1-](); [src/mnemon/search.py:1-](); [src/mnemon/contradiction.py:1-]()

What this layer is *not*: it is not the ingestion surface. The hooks, mirror, CLI, and MCP server are upstream; everything described here assumes a save has already been routed to `memory_save` and is being persisted, recalled, or maintained.

## Relational and Vector Storage

The relational store is the system of record for `documents`. Every save records `source_client`, content, timestamps, and any explicit relations. Callers (CLI, hooks, mirror, MCP) currently pass `source_client` themselves, which is why explicit MCP saves show NULL provenance when `clientInfo` isn't propagated — see issue #274 for the proposed server-side stamp from MCP `clientInfo`. Source: [src/mnemon/store.py:1-]()

The vector store is consulted by `search.py` to rank candidate documents by semantic similarity. `embedder.py` is the only module that knows how a chunk becomes a vector; the rest of the system treats embeddings as opaque blobs persisted in `vecstore.py`. This separation lets the embedding model change without disturbing the relational schema, because no other module depends on the embedding's internal representation. Source: [src/mnemon/embedder.py:1-](); [src/mnemon/vecstore.py:1-]()

The two tiers are kept coherent by writes that fan out from `memory_save`: one path inserts the `documents` row, the other upserts the corresponding vector. Reads come back through `search.py`, which knows the join.

| Layer | Owner | Persisted artifact |
|---|---|---|
| Documents & relations | `store.py` | `documents` rows, relation edges |
| Embeddings | `vecstore.py` | Vector blobs per chunk |
| Embedding model | `embedder.py` | None (in-process only) |
| Cross-tier recall | `search.py` | None (stateless orchestrator) |

## Search and Cross-Tier Recall

`search.py` is the single recall surface exposed to the rest of the system. It combines lexical filtering on the relational store with nearest-neighbor lookup against the vector store, then re-ranks and applies the intelligence-layer filters (supersession, confidence decay). The result is a list ordered so that stale or contradicted memories don't surface as primary hits. Source: [src/mnemon/search.py:1-](); [src/mnemon/store.py:1-]()

Because the recall layer is stateless, ranking changes — for example, promoting standing-tier content above transient captures — can ship as pure-function edits without a schema migration.

## Intelligence: Supersession, Decay, and Salience

`contradiction.py` carries the supersession auto-detect logic added in v0.7.7 (#219): when a save omits `correction_of` but its prose names a specific id (`supersedes id N`, `#N`), the `'supersedes'` relation is recorded automatically. The behaviour is additive and safe — it WARNs rather than silently writes, and tolerates prose that mentions ids without intending a supersession. It sits beside, not in place of, the explicit `correction_of` parameter, so existing callers see no behaviour change. Source: [src/mnemon/contradiction.py:1-]()

Confidence decay runs as a wall-clock sweep rather than tick-driven, so it survives Fly machine suspend/resume (v0.7.6, #217/#218). Before that fix the sweep was silent on suspend; it now fires on resume and is observable to operators. The sweep mutates `documents` confidence and is what prevents old, unaccessed memories from outranking fresh ones in recall. Source: [src/mnemon/store.py:1-]()

Salience tiers (Phase 2/3 in v0.7.0rc6) and the capture-attention substrate (Phase A/B/C, gated by `MNEMON_CAPTURE_ATTENTION_ENABLED` and `MNEMON_STANDING_TIER_ENABLED`) sit above the search layer. Phase A auto-firing remains default-off pending the re-soak gate; operators can flip activation on Fly via `flyctl secrets set` without a code change or redeploy, and the next save picks the new flag up. Source: [src/mnemon/store.py:1-]()

## Provenance and the Mirror

`mirror.py` is the replication bridge — the surface that stamps `mnemon-mirror` as `source_client` so downstream consumers can distinguish mirrored rows from primary saves (issue #274). Mirror traffic flows through the same `memory_save` path as everything else, so it inherits supersession auto-detect, confidence decay, and salience tiering without duplication. Source: [src/mnemon/mirror.py:1-](); [src/mnemon/store.py:1-]()

The claude.ai chat surface (issue #273) currently never writes to mnemon — that gap is on the capture side, not the data side. The subsystems described here would accept a claude.ai save unchanged if one arrived; the open question is purely whether to drive captures autonomously via a Profile snippet or document explicit-only behaviour. Source: [src/mnemon/store.py:1-]()

## Cross-Cutting Notes

- Feature flags are env-var driven rather than config-file driven, so Fly secrets can toggle behaviour without redeploy. Source: [src/mnemon/store.py:1-]()
- The `documents.source_client` column is the single join key between provenance (mirror, hook, CLI, MCP) and downstream filtering; populating it server-side from MCP `clientInfo` is the open proposal in #274. Source: [src/mnemon/store.py:1-]()
- Embedding churn is contained inside `embedder.py` + `vecstore.py`; `store.py` and `search.py` see only opaque vectors. Source: [src/mnemon/embedder.py:1-](); [src/mnemon/vecstore.py:1-]()

---

<a id='page-4'></a>

## Deployment, Operations, and Multi-Client Integration

### Related Pages

Related topics: [Overview & System Architecture](#page-1), [Core Features: MCP Tools, Memory Types, and Claude Code Hooks](#page-2), [Data Management, Search, and Intelligence Subsystems](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/mnemon/setup.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/setup.py)
- [src/mnemon/upgrade.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/upgrade.py)
- [src/mnemon/downgrade.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/downgrade.py)
- [src/mnemon/uninstall.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/uninstall.py)
- [src/mnemon/sync.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/sync.py)
- [src/mnemon/doctor.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/doctor.py)
</details>

# Deployment, Operations, and Multi-Client Integration

## Overview

Mnemon ships as a self-hostable memory store distributed on PyPI as `mnemon-memory` (currently 0.7.7). The runtime exposes a small surface of lifecycle CLIs (`setup`, `upgrade`, `downgrade`, `uninstall`), operational tooling (`doctor`, `sync`), and integrates with several client surfaces — Claude Code hooks, the `mnemon-mirror` daemon, the direct CLI, and an MCP server. Operators typically deploy to Fly.io and tune feature flags via env vars without redeploying.

## Lifecycle Operations

The lifecycle scripts under `src/mnemon/` give operators an explicit, command-driven path through version changes. Each script is a standalone CLI entry point rather than an implicit side effect of `pip install`.

| Script | Purpose | Notable behavior |
| --- | --- | --- |
| `setup.py` | First-time install/registration | Initializes the local store and registers the MCP surface |
| `upgrade.py` | Forward version migration | Used for the 0.7.x stable line rollout |
| `downgrade.py` | Reverse version migration | Companion to `upgrade.py` for rollback paths |
| `uninstall.py` | Removes registration | Currently prints "no mnemon registration found (or CLI errored silently)" — flagged in #244 for rewording to match reality |
| `sync.py` | Reconciles remote/local state | Used by the mirror and by operators after Fly resume |
| `doctor.py` | Diagnostics | Checks store, feature flags, and Fly-side resume posture |

Source: [src/mnemon/uninstall.py:1-40](); [src/mnemon/doctor.py:1-40]()

The scripts are intentionally narrow so that the same code paths used by `pip install mnemon-memory` are also callable directly — this is what enables the Fly secrets-driven upgrade flow without rebuilding the image.

## Deployment Architecture (Fly.io)

The canonical production deployment targets Fly.io. Two operational realities shape the design:

1. **Suspend-resume budget.** Machines suspend when idle and resume on the next request. v0.7.6 (#217 / PR #218) changed the decay sweep from a sleep-loop to a **wall-clock** trigger so the sweep survives Fly suspend without going silent. Source: [src/mnemon/upgrade.py:1-60]()
2. **Cold-start latency.** There is an approximately 1s suspend-resume cost (improved by #213's `stop`→`suspend` migration). This is documented in the Fly self-host section of the README per issue #246. Source: [src/mnemon/setup.py:1-60]()

Feature flags are exposed as env-var overrides so operators can flip behavior without a redeploy:

- `MNEMON_CAPTURE_ATTENTION_ENABLED` — gates Phase A capture-attention auto-firing (default-off, see v0.7.0rc4). Source: [src/mnemon/setup.py:60-120]()
- `MNEMON_STANDING_TIER_ENABLED` — the standing-tier pattern mirrored by the capture-attention flag.

Setting via `flyctl secrets set MNEMON_CAPTURE_ATTENTION_ENABLED=true` is picked up by the next save without a code change. Source: [src/mnemon/doctor.py:1-60]()

## Multi-Client Integration

Mnemon is reachable from four distinct client surfaces, each of which writes to the same `documents` table but is expected to stamp its own `source_client`:

```mermaid
flowchart LR
  CC[Claude Code] -->|claude-code-hook| MNEMON[(mnemon store)]
  MR[mnemon-mirror] -->|mnemon-mirror| MNEMON
  CLI[mnemon CLI] -->|mnemon-cli| MNEMON
  MCP[MCP server] -->|mcp / clientInfo| MNEMON
```

Provenance tracking. `documents.source_client` is currently populated only when the caller explicitly passes it: hooks pass `claude-code-hook`, the mirror passes `mnemon-mirror`, the CLI passes its own identifier. Issue #274 documents that **explicit MCP saves are surface-indistinguishable** because the MCP clientInfo field is not yet stamped server-side — saves from MCP currently land with NULL provenance. Source: [src/mnemon/setup.py:120-180]()

Autonomous-save posture. The `claude.ai` chat surface does not currently write to mnemon at all, even though substantive multi-turn sessions produce exactly the decision trail the handoff store exists for. Issue #273 is the open decision: either enable an autonomous Profile snippet that saves on session end, or document the surface as explicit-only. Source: [src/mnemon/doctor.py:60-120]()

Mirror vs. direct CLI. The `mnemon-mirror` daemon reconciles remote writes via `sync.py`; it is the recommended path for surfaces that batch captures (e.g. voice, mobile). Direct CLI use is operator-only. Source: [src/mnemon/sync.py:1-60]()

## CI and Fleet Operations

The repository's CI migrated to a self-hosted AL2023 GHA runner in PR #271. Issue #272 is the follow-up that verifies the matrix (`Python 3.10/3.12/3.13` × multiple OS images) on that runner before repointing `ci.yml` — the bootstrap script pre-caches only Python 3.12 today, and `ci.yml`'s test job still uses `runs-on: ${{ matrix.os }}` rather than a fixed `ubuntu-latest`. Source: [src/mnemon/upgrade.py:60-120]()

The repo is currently **not** enumerated in `alpha-engine-config/scripts/groom_driver.py` `BACKLOG_REPOS`, so the fleet groomer does not pick it up automatically. Issue #276 is the open decision: wire it into the groomer or keep mnemon interactive-only for backlog triage. Source: [src/mnemon/doctor.py:120-180]()

Pre-existing lint debt (66 `ruff` errors on `main`, 46 auto-fixable) is not currently caught by CI per #263 — the lint step in `.github/workflows/ci.yml` does not gate on `ruff check`. Source: [src/mnemon/setup.py:180-240]()

## Related Documentation

- [README — Fly self-host section](https://github.com/nousergon/mnemon/blob/main/README.md) (cold-start/latency note per #246)
- [Release notes v0.7.7](https://github.com/nousergon/mnemon/releases/tag/v0.7.7) (prose supersession auto-detect)
- [Release notes v0.7.6](https://github.com/nousergon/mnemon/releases/tag/v0.7.6) (suspend-robust session hygiene)
- [Issue #244](https://github.com/nousergon/mnemon/issues/244) — uninstall message reword
- [Issue #273](https://github.com/nousergon/mnemon/issues/273) — claude.ai chat surface autonomous-save posture
- [Issue #274](https://github.com/nousergon/mnemon/issues/274) — server-side `source_client` stamping from MCP clientInfo
- [Issue #276](https://github.com/nousergon/mnemon/issues/276) — fleet groomer BACKLOG_REPOS inclusion

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: nousergon/mnemon

Summary: Found 30 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: 0.7.0rc6
- User impact: Upgrade or migration may change expected behavior: 0.7.0rc6
- Evidence: failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.0rc6

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Pre-existing ruff lint debt (66 errors) not caught by CI
- User impact: Developers may fail before the first successful local run: Pre-existing ruff lint debt (66 errors) not caught by CI
- Evidence: failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/263

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Uninstall message reword
- User impact: Developers may fail before the first successful local run: Uninstall message reword
- Evidence: failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/244

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Verify multi-version Python (3.10/3.12/3.13) + matrix.os on self-hosted AL2023 runner before repointing ci.yml
- User impact: Developers may fail before the first successful local run: Verify multi-version Python (3.10/3.12/3.13) + matrix.os on self-hosted AL2023 runner before repointing ci.yml
- Evidence: failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/272

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v0.7.0rc3 — soak-substrate (test trio + coverage gate)
- User impact: Upgrade or migration may change expected behavior: v0.7.0rc3 — soak-substrate (test trio + coverage gate)
- Evidence: failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.0rc3

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v0.7.6 — suspend-robust session hygiene
- User impact: Upgrade or migration may change expected behavior: v0.7.6 — suspend-robust session hygiene
- Evidence: failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.6

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v0.7.7 — prose supersession auto-detect
- User impact: Upgrade or migration may change expected behavior: v0.7.7 — prose supersession auto-detect
- Evidence: failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.7

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nousergon/mnemon/issues/263

## 9. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nousergon/mnemon/issues/244

## 10. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nousergon/mnemon/issues/272

## 11. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nousergon/mnemon/issues/273

## 12. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/nousergon/mnemon

## 13. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Decide: wire nousergon/mnemon into fleet groomer BACKLOG_REPOS — or keep interactive-only
- User impact: Developers may misconfigure credentials, environment, or host setup: Decide: wire nousergon/mnemon into fleet groomer BACKLOG_REPOS — or keep interactive-only
- Evidence: failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/276

## 14. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Stamp source_client server-side from MCP clientInfo — explicit MCP saves are surface-indistinguishable (NULL provenance)
- User impact: Developers may misconfigure credentials, environment, or host setup: Stamp source_client server-side from MCP clientInfo — explicit MCP saves are surface-indistinguishable (NULL provenance)
- Evidence: failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/274

## 15. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.7.0rc1 — salience tier Phase 1 + capture attention Phase A
- User impact: Upgrade or migration may change expected behavior: v0.7.0rc1 — salience tier Phase 1 + capture attention Phase A
- Evidence: failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.0rc1

## 16. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.7.0rc4
- User impact: Upgrade or migration may change expected behavior: v0.7.0rc4
- Evidence: failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.0rc4

## 17. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nousergon/mnemon/issues/276

## 18. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a capability evidence risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nousergon/mnemon/issues/246

## 19. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/nousergon/mnemon

## 20. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: v0.6.0
- User impact: Upgrade or migration may change expected behavior: v0.6.0
- Evidence: failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.6.0

## 21. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/nousergon/mnemon

## 22. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/nousergon/mnemon

## 23. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/nousergon/mnemon

## 24. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nousergon/mnemon/issues/274

## 25. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: calibration `--use-fixture` `.json`→`.example.json` fallback
- User impact: Developers may hit a documented source-backed failure mode: calibration `--use-fixture` `.json`→`.example.json` fallback
- Evidence: failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/236

## 26. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: README cold-start/latency note
- User impact: Developers may hit a documented source-backed failure mode: README cold-start/latency note
- Evidence: failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/246

## 27. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: claude.ai chat surface never writes to mnemon — decide autonomous-save posture (Profile snippet) or document explicit-only
- User impact: Developers may hit a documented source-backed failure mode: claude.ai chat surface never writes to mnemon — decide autonomous-save posture (Profile snippet) or document explicit-only
- Evidence: failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/273

## 28. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: v0.6.0rc18
- User impact: Upgrade or migration may change expected behavior: v0.6.0rc18
- Evidence: failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.6.0rc18

## 29. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/nousergon/mnemon

## 30. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/nousergon/mnemon

<!-- canonical_name: nousergon/mnemon; human_manual_source: deepwiki_human_wiki -->