# memtomem-stm - Doramagic AI Context Pack

> Positioning: a pre-install experience and judgment asset. It helps the host AI get off to a good start, but it does not mean the project has already been installed, run, or validated.

## Sufficiency Principle

- **Sufficiency over compression**: The AI Context Pack should be sufficient for the host AI to understand the project's value, capability boundaries, entrypoints, risks, and evidence sources before starting work; it may be layered, but it does not aim for the shortest possible summary.
- **Compression policy**: Compress only noise and duplication, never context that affects judgment or the quality of the work.

## How the Host AI Should Use This

You are reading the AI Context Pack that Doramagic compiled for memtomem-stm. Treat it as pre-work context: help the user understand who it fits, what it can do, how to start, what must be verified after install, and where the risks are. Do not claim that you have already installed, run, or executed the target project.

## Claim Consumption Rules

- **Fact source**: Repo Evidence + Claim/Evidence Graph; the Human Wiki only supplies salience, terminology, and narrative structure.
- **Minimum status for a fact**: `supported`
- `supported`: May be used as a project fact, but the answer must cite the claim_id and evidence path.
- `weak`: Usable only as a low-confidence lead; the user must be asked to keep verifying.
- `inferred`: Usable only for risk notes or open questions; must not be packaged as a project fact.
- `unverified`: Must not be used as fact; state clearly that evidence is insufficient.
- `contradicted`: Must show the conflicting sources and must not force a single version on the user's behalf.

## Who It Fits Best

- **Developers already using host AIs such as Claude/Codex/Cursor/Gemini**: The README or plugin config mentions multiple host AIs. Evidence: `README.md` Claim: `clm_0002` supported 0.86

## What It Can Do

- **Command-Line Startup or Install Flow** (Verify after install): The project documentation contains runnable commands; real use requires running them in a local or host environment. Evidence: `README.md` Claim: `clm_0001` supported 0.86

## How to Start

- `pip install memtomem-stm` Evidence: `README.md` Claim: `clm_0003` supported 0.86
- `uv tool install memtomem-stm     # install mms / memtomem-stm as global CLI tools` Evidence: `README.md` Claim: `clm_0004` supported 0.86
- `claude mcp add mms -s user -- mms` Evidence: `README.md` Claim: `clm_0005` supported 0.86

## Continue-or-Stop Decision Card

- **Current recommendation**: Sandbox-trial permissions first
- **Why**: The project has signals of install commands, host configuration, or local writes; do not go straight into your primary environment—trial it in isolation first.

### 30-Second Read

- **What to do now**: Sandbox-trial permissions first
- **Minimum safe next step**: Run Prompt Preview first; if you still want to install, trial only in an isolated environment
- **Do not trust yet**: Tool permission boundaries cannot be trusted before install.
- **Continuing will touch**: Command execution, Host AI configuration, Local environment or project files

### What You Can Trust Now

- **Target-audience signal: Developers already using host AIs such as Claude/Codex/Cursor/Gemini** (supported): Backed by a supported claim or project evidence, but that still is not the same as real install results. Evidence: `README.md` Claim: `clm_0002` supported 0.86
- **Capability exists: Command-Line Startup or Install Flow** (supported): You can trust that the project contains signals of this capability; whether it fits your specific task still needs trial or after-install verification. Evidence: `README.md` Claim: `clm_0001` supported 0.86
- **There are Quick Start / install-command signals** (supported): You can trust that the docs mention a startup or install entrypoint; do not run it directly in your primary environment because of that. Evidence: `README.md` Claim: `clm_0003` supported 0.86

### What You Cannot Trust Yet

- **Tool permission boundaries cannot be trusted before install.** (unverified): MCP/tool projects usually touch files, the network, the browser, or external APIs, so permissions and logs must be checked for real.
- **Real output quality cannot be trusted before install.** (unverified): Prompt Preview can only show how it guides you; it cannot prove result quality in the real project.
- **Host AI version compatibility cannot be trusted before install.** (unverified): Host loading rules and version differences across Claude, Cursor, Codex, Gemini, and others must be verified in a real environment.
- **That it will not pollute your existing host AI's behavior cannot be trusted directly.** (inferred): Skill, plugin, and AGENTS/CLAUDE/GEMINI instructions may change the host AI's default behavior. Evidence: `CLAUDE.md`
- **Safe rollback cannot be assumed by default.** (unverified): Unless the project clearly provides uninstall and recovery instructions, verify in an isolated environment first.
- **After a real install, is it compatible with the user's current host AI version?** (unverified): Compatibility can only be verified in the actual host environment.
- **Does the project's output quality meet the user's specific task?** (unverified): The pre-install preview can only show flow and boundaries; it cannot replace real evaluation.
- **Do the install commands require network access, permissions, or global writes?** (unverified): This affects install risk in both enterprise and personal environments. Evidence: `README.md`

### What Continuing Will Touch

- **Command execution**: Package managers, network downloads, the local plugin directory, project config, or the user's home directory. Why: Running the very first command can already change your environment; decide whether it is worth running first. Evidence: `README.md`
- **Host AI configuration**: The plugin, Skill, or rule-loading config of hosts like Claude/Codex/Cursor/Gemini/OpenCode. Why: Host configuration changes how the AI works afterward and may conflict with the user's existing rules. Evidence: `CLAUDE.md`
- **Local environment or project files**: Install results, plugin caches, project config, or local dependency directories. Why: The write scope and rollback path cannot be proven before install and need isolated verification. Evidence: `README.md`
- **Host AI context**: The AI Context Pack, Prompt Preview, Skill routing, risk rules, and project facts. Why: Importing context affects the host AI's later judgment, so avoid packaging unverified items as facts.

### Minimum Safe Next Steps

- **Run Prompt Preview first**: Use a pre-install interactive trial to judge whether the way of working fits; it needs no authorization or environment change. (applies when: Applies to any project, especially when output quality is unknown.)
- **Trial-install only in an isolated directory or a test account**: Avoid letting install commands pollute your primary host AI, real projects, or home directory. (applies when: When there are signals of command execution, plugin config, or local writes.)
- **Back up your host AI configuration first**: Skill, plugin, and rule files may change the default behavior of Claude/Cursor/Codex. (applies when: When there is a plugin manifest, a Skill, or a host rule entrypoint.)
- **After install, verify just one minimal task**: Verify loading, compatibility, output quality, and rollback first, then decide whether to use it deeply. (applies when: When moving from a trial into a real workflow.)

### Exit Plan

- **Preserve the pre-install state**: Record the original host config and project state so you can later judge whether it is recoverable.
- **Be ready to remove the host plugin / Skill / rule entrypoint**: If behavior is off after the trial install, you can restore the host AI to its pre-trial state.
- **Record the install commands and written paths**: Without clear uninstall instructions, you at least need to know which directories or configs to clean up manually.
- **If there is no rollback path, do not enter your primary environment**: No rollback is a blocker before continuing; do not proceed on trust or luck.

## What Can Only Be Previewed

- Explain who the project fits and what it can do
- Demonstrate a typical conversation flow based on project docs
- Help the user decide whether it is worth installing or researching further

## What Must Be Verified After Install

- Actually installing the Skill, plugin, or CLI
- Running scripts, modifying local files, or accessing external services
- Verifying real output quality, performance, and compatibility

## Boundary & Risk Decision Card

- **Mistaking the pre-install preview for a real run**: The user may overestimate how much configuration, permission, and compatibility verification the project has already done. Mitigation: Clearly separate prompt_preview_can_do from runtime_required. Claim: `clm_0006` inferred 0.45
- **Command execution will modify the local environment**: Install commands may write to the user's home directory, the host plugin directory, or project configuration. Mitigation: Run in an isolated environment or a test account first. Evidence: `README.md` Claim: `clm_0007` supported 0.86
- **To confirm**: After a real install, is it compatible with the user's current host AI version?. Why: Compatibility can only be verified in the actual host environment.
- **To confirm**: Does the project's output quality meet the user's specific task?. Why: The pre-install preview can only show flow and boundaries; it cannot replace real evaluation.
- **To confirm**: Do the install commands require network access, permissions, or global writes?. Why: This affects install risk in both enterprise and personal environments.

## Pre-Work Working Context

### Loading Order

- First read how_to_use.host_ai_instruction to establish the boundaries of this pre-install judgment asset.
- Read claim_graph_summary to confirm facts come from the Claim/Evidence Graph, not the Human Wiki narrative.
- Then read intended_users, capabilities, and quick_start_candidates to judge whether the user is a match.
- When you need to carry out a concrete task, check role_skill_index first, then evidence_index.
- For real install, file modification, network access, performance, or compatibility questions, turn to risk_card and boundaries.runtime_required.

### Task Routes

- **Command-Line Startup or Install Flow**: State that this is an after-install capability first, then give a pre-install checklist. Boundary: Must be verified after a real install or run. Evidence: `README.md` Claim: `clm_0001` supported 0.86

### Context Scale

- Total files: 102
- Important-file coverage: 40/102
- Evidence index entries: 50
- Role / Skill entries: 13

### Handling Insufficient Evidence

- **missing_evidence**: State that evidence is insufficient and ask the user for the target file, a README section, or after-install verification records; do not fill in facts.
- **out_of_scope_request**: State that the task is beyond the current AI Context Pack's evidence scope and suggest the user check the Human Manual or verify after a real install.
- **runtime_request**: Provide a pre-install checklist and command sources, but do not run commands for the user or claim they have been run.
- **source_conflict**: Show the conflicting sources side by side, mark them as unverified, and do not force a single version.

## Prompt Recipes

### Fit assessment

- Goal: Judge whether this project fits the user's current task.
- Expected output: A fit conclusion, key reasons, evidence citations, what can be previewed before install, what must be verified after install, and a next-step recommendation.

```text
Based on the AI Context Pack for memtomem-stm, ask me 3 necessary questions first, then judge whether it fits my task. The answer must cover: who it fits, what it can do, what it cannot do, whether it is worth installing, and where the evidence comes from. Every project fact must cite evidence_refs, source_paths, or a claim_id.
```

### Pre-install experience

- Goal: Let the user feel the core workflow before installing, while avoiding packaging the preview as real capability or a marketing promise.
- Expected output: An experience script with boundary labels, an after-install verification checklist, and a cautious recommendation; with no real-run promises or strong marketing language.

```text
Treat memtomem-stm as a pre-install experience asset, not an already-installed tool or a real runtime environment.

Output exactly four parts:
1. Ask me 3 necessary questions first.
2. Give an "experience script": use the three labels [Previewable before install], [Must verify after install], and [Insufficient evidence] to show how it might guide the workflow.
3. Give an after-install verification checklist: list which capabilities can only be confirmed after a real install, real host loading, and a real project run.
4. Give a cautious recommendation: only "worth researching/trialing further", "add information before deciding", or "not recommended to continue"; do not endorse the project.

Hard boundaries:
- Do not claim you have installed, run, executed tests, modified files, or produced real results.
- Do not write promise-like phrasing such as "auto-adapts", "guarantees passing", "perfect fit", or "strongly recommend installing".
- If you describe how it works after install, you must use a conditional such as "if installed successfully and the host loads the Skill correctly, it might...".
- The experience script may only be written as "example lines / hypothetical flow": use "might ask / might suggest / might show", not "has written, has generated, has passed, is running, is generating".
- Prompt Preview does not hand out install commands; if the user is ready to trial, only prompt them to read Quick Start and the Risk Card first and to verify in an isolated environment.
- Every project fact must come from a supported claim, evidence_refs, or source_paths; inferred/unverified items can only be risks or open questions.

```

### Role / Skill selection

- Goal: Pick the best-matching asset from the project's roles or Skills.
- Expected output: A list of candidate roles or Skills, each with an applicable scenario, evidence paths, risk boundary, and whether after-install verification is needed.

```text
Read role_skill_index and recommend 3-5 of the most relevant roles or Skills for my target task. For each recommendation, state the applicable scenario, likely output, risk boundary, and evidence_refs.
```

### Risk pre-check

- Goal: Identify environment, permission, rule-conflict, and quality risks before installing or adopting.
- Expected output: A checklist of environment, permission, dependency, license, host-conflict, quality risk, and unknown items.

```text
Based on risk_card, boundaries, and quick_start_candidates, give me a pre-install risk pre-check list. Do not run commands for me; only explain what I should check, why, and what impact a failure would have.
```

### Host AI kickoff instruction

- Goal: Turn the project context into a host AI instruction for the start of a conversation.
- Expected output: A pre-work instruction with clear boundaries and clear evidence citations, suitable to copy to a host AI.

```text
Based on the AI Context Pack for memtomem-stm, generate a pre-work instruction I can paste to my host AI. This instruction must obey not_runtime=true and must not claim the project has been installed, run, or produced real results.
```

## Role / Skill Index

- Indexed 13 role / Skill / project-doc entries.

- **memtomem-stm** (project_doc): Official website & docs: https://memtomem.com https://memtomem.com Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `README.md`
- **Tutorial notebooks** (project_doc): 한국어 사용자 분들께 : 노트북은 유지보수 편의와 GitHub 인덱싱을 위해 영어로 작성되어 있지만, 코드 셀은 그대로 실행하시면 됩니다. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `notebooks/README.md`
- **Claude Code notes — memtomem-stm** (project_doc): Short-term memory MCP proxy. For what it does see README.md ; for setup and project layout see CONTRIBUTING.md ; for architecture see docs/ . This file only captures the few things Claude Code needs in context that aren't obvious from those docs. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `CLAUDE.md`
- **Contributing to memtomem-stm** (project_doc): Thank you for your interest in contributing to memtomem-stm! Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `CONTRIBUTING.md`
- **Security Policy** (project_doc): Please report security issues via GitHub private vulnerability advisory https://github.com/memtomem/memtomem-stm/security/advisories/new . Do NOT open public issues for vulnerabilities. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `SECURITY.md`
- **Response Caching & Auto-Indexing** (project_doc): Proxied tool responses are cached in SQLite to avoid repeated upstream calls: Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/caching.md`
- **CLI Reference** (project_doc): memtomem-stm ships three console scripts: Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/cli.md`
- **Compression Strategies** (project_doc): memtomem-stm has 10 compression strategies. The CLI's --compression flag exposes 5 of them auto , none , truncate , selective , hybrid ; the remaining five are selected via the config file. The default is auto , which lets auto select strategy pick per response. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/compression.md`
- **Configuration Reference** (project_doc): memtomem-stm reads configuration from two sources, in order of precedence: Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/configuration.md`
- **Selection Telemetry** (project_doc): Append-only JSONL log of tool selection and execution outcomes 467 . The proxy sits in the call path, so it can record what an advisory analyzer never sees: which tool the client model actually called, out of which advertised candidate set, and how the call went. This log is the substrate for offline replay/eval 468 and later learning stages 469/ 470 , and the landing zone for the STM-native hard filter's reject rea… Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/selection-telemetry.md`
- **Proactive Memory Surfacing** (project_doc): When your agent calls a proxied tool, STM automatically: Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/surfacing.md`
- **Changelog** (project_doc): All notable changes will be documented in this file. Format: Keep a Changelog https://keepachangelog.com/en/1.1.0/ Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `CHANGELOG.md`
- **memtomem Individual Contributor License Agreement** (project_doc): memtomem Individual Contributor License Agreement Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `CLA.md`

## Evidence Index

- Indexed 50 evidence entries.

- **memtomem-stm** (documentation): Official website & docs: https://memtomem.com https://memtomem.com Evidence: `README.md`
- **Tutorial notebooks** (documentation): 한국어 사용자 분들께 : 노트북은 유지보수 편의와 GitHub 인덱싱을 위해 영어로 작성되어 있지만, 코드 셀은 그대로 실행하시면 됩니다. Evidence: `notebooks/README.md`
- **Claude Code notes — memtomem-stm** (documentation): Short-term memory MCP proxy. For what it does see README.md ; for setup and project layout see CONTRIBUTING.md ; for architecture see docs/ . This file only captures the few things Claude Code needs in context that aren't obvious from those docs. Evidence: `CLAUDE.md`
- **Contributing to memtomem-stm** (documentation): Thank you for your interest in contributing to memtomem-stm! Evidence: `CONTRIBUTING.md`
- **License** (source_file): Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ Evidence: `LICENSE`
- **Security Policy** (documentation): Please report security issues via GitHub private vulnerability advisory https://github.com/memtomem/memtomem-stm/security/advisories/new . Do NOT open public issues for vulnerabilities. Evidence: `SECURITY.md`
- **Response Caching & Auto-Indexing** (documentation): Proxied tool responses are cached in SQLite to avoid repeated upstream calls: Evidence: `docs/caching.md`
- **CLI Reference** (documentation): memtomem-stm ships three console scripts: Evidence: `docs/cli.md`
- **Compression Strategies** (documentation): memtomem-stm has 10 compression strategies. The CLI's --compression flag exposes 5 of them auto , none , truncate , selective , hybrid ; the remaining five are selected via the config file. The default is auto , which lets auto select strategy pick per response. Evidence: `docs/compression.md`
- **Configuration Reference** (documentation): memtomem-stm reads configuration from two sources, in order of precedence: Evidence: `docs/configuration.md`
- **Selection Telemetry** (documentation): Append-only JSONL log of tool selection and execution outcomes 467 . The proxy sits in the call path, so it can record what an advisory analyzer never sees: which tool the client model actually called, out of which advertised candidate set, and how the call went. This log is the substrate for offline replay/eval 468 and later learning stages 469/ 470 , and the landing zone for the STM-native hard filter's reject reasons 465 — replay sees the tools that were withheld from the advertisement, not just the ones in it. Evidence: `docs/selection-telemetry.md`
- **Proactive Memory Surfacing** (documentation): When your agent calls a proxied tool, STM automatically: Evidence: `docs/surfacing.md`
- **request spawn launches a detached child iff our config's lock is free;** (source_file): def color on - bool ⋮---- def ok s: str - str ⋮---- def warn s: str - str ⋮---- def load config - STMConfig ⋮---- def as int value: Any, default: int = -1 - int ⋮---- def as float value: Any, default: float - float ⋮---- def live foreign daemons config: STMConfig - list dict str, Any ⋮---- current = config fingerprint config live: list dict str, Any = ⋮---- pid = as int hs.get "pid", -1 host = hs.get "host" port = hs.get "port" ⋮---- def configure logging config: STMConfig, , detached: bool - None ⋮---- level = getattr logging, config.log level, logging.WARNING handler: logging.Handler ⋮---- logpath = config.data dir / "stm-daemon.log" .expanduser ⋮---- handler = logging.FileHandler logpath… Evidence: `src/memtomem_stm/cli/daemon_cmd.py`
- **Codex's only native non-MCP tools that fire PostToolUse. apply patch** (source_file): @dataclass frozen=True, slots=True class CanonicalHookCall ⋮---- event type: str tool name: str canonical tool: str = "" tool input: dict str, Any = field default factory=dict tool response: Any = None tool response text: str = "" host tag: str = "claude" ⋮---- def to wire self - dict str, Any ⋮---- @classmethod def from wire cls, data: Any - "CanonicalHookCall None" ⋮---- tool input = data.get "tool input" ⋮---- class HostHookAdapter ABC ⋮---- host tag: ClassVar str can replace output: ClassVar bool native tool map: ClassVar dict str, str ⋮---- @abstractmethod def parse self, payload: dict str, Any - CanonicalHookCall None ⋮---- def serialize self, rendered: dict str, Any - str ⋮---- class… Evidence: `src/memtomem_stm/cli/hook_adapter.py`
- **Indent non-blank lines only — TOML array-of-tables separators are** (source_file): logger = logging.getLogger name ⋮---- SURFACED OPEN = " " SURFACED CLOSE = " " ⋮---- DEFAULT SURFACE TOOLS = READLIKE SURFACE TOOLS ⋮---- COMPRESS SENTINEL = "⟦stm-compressed⟧" ⋮---- SAFE DAEMON BUDGET = 256 1024 ⋮---- METRICS BUSY TIMEOUT MS = 250 ⋮---- def surface tools - frozenset str ⋮---- raw = os.environ.get "MEMTOMEM STM HOOK SURFACE TOOLS" ⋮---- tools: set str = set saw token = False ⋮---- saw token = True canonical = canonicalize tool token token ⋮---- def hook budget seconds - float ⋮---- raw = os.environ.get "MEMTOMEM STM SURFACING TIMEOUT SECONDS" ⋮---- configured = float raw if raw else 3.0 ⋮---- configured = 3.0 ⋮---- def tool response to text tool response: Any - str ⋮---- pa… Evidence: `src/memtomem_stm/cli/hook_cmd.py`
- **Hook Hosts** (source_file): STM EXECUTABLES: frozenset str = frozenset {"mms", "memtomem-stm", "memtomem-stm-proxy"} ⋮---- class HookInstallError Exception ⋮---- def is stm hook command command: str - bool ⋮---- tokens = shlex.split command ⋮---- tokens = command.split ⋮---- def is stm command handler handler: Any - bool ⋮---- def entry has stm handler entry: Any - bool ⋮---- def ensure dict parent: dict str, Any , key: str - dict str, Any ⋮---- val = parent.get key ⋮---- val = {} ⋮---- def ensure list parent: dict str, Any , key: str - list Any ⋮---- val = ⋮---- def nested install data: dict str, Any , command: str, matcher: str None - dict str, Any ⋮---- entries = ensure list ensure dict data, "hooks" , "PostToolUse… Evidence: `src/memtomem_stm/cli/hook_hosts.py`
- **--project NAME path** (source_file): REGISTRY EMPTY MSG = ⋮---- def show no marker no git text cwd: Path - str ⋮---- def show git no marker text root: Path - str ⋮---- @click.group name="project" def project group - None ⋮---- def project payload p: Project - dict ⋮---- payload = { ⋮---- def resolve project for mutation project name: str None - Project ⋮---- p = detect project Path.cwd ⋮---- --project NAME path idx = state.load projects index matches = entry for entry in idx.projects if entry.name == project name ⋮---- entry = matches 0 marker = Path entry.path / state.PROJECT MARKER RELPATH ⋮---- cfg = state.load project config marker ⋮---- def refresh index name: str, root: Path - None ⋮---- """Upsert name, root into the pro… Evidence: `src/memtomem_stm/cli/mms_project.py`
- **Structural guard: the rest of the CLI assumes top-level dict with a dict** (source_file): PREFIX RE = re.compile r"^ a-zA-Z a-zA-Z0-9 $" ⋮---- DEFAULT CONFIG = Path "~/.memtomem/stm proxy.json" logger = logging.getLogger name ⋮---- def color on - bool ⋮---- def err s: str - str ⋮---- def warn s: str - str ⋮---- def ok s: str - str ⋮---- def bad s: str - str ⋮---- def hdr s: str - str ⋮---- def split args args str: str - list str ⋮---- lex = shlex.shlex args str, posix=True ⋮---- def load config path: Path - dict str, Any ⋮---- resolved = config path.expanduser .resolve ⋮---- data = json.loads resolved.read text encoding="utf-8" ⋮---- Structural guard: the rest of the CLI assumes top-level dict with a dict upstream servers . Without this, a valid-but-wrong-shape JSON e.g. a list… Evidence: `src/memtomem_stm/cli/proxy.py`
- **Config** (source_file): class LangfuseConfig BaseModel ⋮---- enabled: bool = False public key: str = "" secret key: str = "" host: str = "" sampling rate: float = Field default=1.0, ge=0.0, le=1.0 """Fraction of proxy calls to trace 0.0–1.0 . Default 1.0 = all.""" ⋮---- @model validator mode="after" def require keys when enabled self - "LangfuseConfig" ⋮---- @model validator mode="after" def require langfuse package when enabled self - "LangfuseConfig" ⋮---- class HookCompressionConfig BaseModel ⋮---- max chars: int = Field default=16000, gt=0 ⋮---- class HookConfig BaseModel ⋮---- use daemon: bool = True ⋮---- daemon timeout seconds: float = Field default=2.5, gt=0.0 ⋮---- fallback: Literal "skip", "cold" = "skip… Evidence: `src/memtomem_stm/config.py`
- **Server** (source_file): logger = logging.getLogger name ⋮---- READ TIMEOUT SECONDS = 30.0 ⋮---- WRITE TIMEOUT SECONDS = 30.0 ⋮---- async def quiet coro: Any, what: str - None ⋮---- def direct child pids - set int ⋮---- out = subprocess.run ⋮---- LEAK KILL ESCALATE SECONDS = 2.0 ⋮---- def signal pid pid: int, sig: int - None ⋮---- pgid = os.getpgid pid ⋮---- async def terminate leaked children pids: set int - None ⋮---- deadline = asyncio.get running loop .time + LEAK KILL ESCALATE SECONDS remaining = {pid for pid in pids if discovery.is pid alive pid } ⋮---- remaining = {pid for pid in remaining if discovery.is pid alive pid } ⋮---- class DaemonServer ⋮---- LOCK ACQUIRE RETRY SECONDS = 1.5 LOCK ACQUIRE POLL SECOND… Evidence: `src/memtomem_stm/daemon/server.py`
- **Tracing** (source_file): logger = logging.getLogger name ⋮---- langfuse client: Any = None sampling rate: float = 1.0 SERVICE NAME = "memtomem-stm" ⋮---- warned observation failure = False warned observation failure lock = threading.Lock ⋮---- def log observation failure stage: str - None ⋮---- first = not warned observation failure warned observation failure = True ⋮---- def init langfuse config: object, , service name: str = SERVICE NAME - Any ⋮---- sampling rate = getattr config, "sampling rate", 1.0 ⋮---- kwargs: dict str, Any = {} ⋮---- langfuse client = Langfuse kwargs ⋮---- def get langfuse - Any ⋮---- def shutdown langfuse client: Any = None - None ⋮---- c = client or langfuse client ⋮---- class SafeObserva… Evidence: `src/memtomem_stm/observability/tracing.py`
- **Substrings that flag a response embedding a TRANSIENT retrieval key pointing** (source_file): logger = logging.getLogger name ⋮---- CREATE TABLE = """ ⋮---- CREATE INDEX = """ ⋮---- @dataclass class CacheEntry ⋮---- result: str created at: float ttl seconds: float None ⋮---- def is expired self - bool ⋮---- def make key server: str, tool: str, args: dict str, Any - str ⋮---- raw = f"{server}:{tool}:{json.dumps args, sort keys=True }" ⋮---- Substrings that flag a response embedding a TRANSIENT retrieval key pointing into a process-local pending store. Such payloads must never be cached/served: the key outlives neither a process restart nor the shorter pending-store TTL, so a cache hit would hand the agent a dead stm proxy read more / stm proxy select chunks key with the response tail… Evidence: `src/memtomem_stm/proxy/cache.py`
- **Prompt injection heuristic patterns — common LLM manipulation attempts** (source_file): CODE FENCE RE = re.compile r" ^ \n + " SCRIPT STYLE RE = re.compile r" \s\S ? ", re.I HTML TAG RE = re.compile r" ?\s /? " CLOSE TAG RE = re.compile r" " MULTI NEWLINE RE = re.compile r"\n{3,}" LINK LINE RE = re.compile r"^\s - \s \ . ?\ \ https?://\S+\ " BARE URL LINE RE = re.compile r"^\s - ?\s https?://\S+\s $" GENERIC RE = re.compile r" A-Z \w{0,60} + " ⋮---- Prompt injection heuristic patterns — common LLM manipulation attempts INJECTION PATTERNS = ⋮---- logger = logging.getLogger name ⋮---- class ContentCleaner Protocol ⋮---- def clean self, text: str - str: ... ⋮---- class DefaultContentCleaner ⋮---- def init self, config: object None = None - None ⋮---- Accept a CleaningConfig or an… Evidence: `src/memtomem_stm/proxy/cleaning.py`
- **A tuple with no non-finite float still round-trips through json as an** (source_file): httpx = None ⋮---- logger = logging.getLogger name ⋮---- QueryRelevanceScorer = BM25Scorer ⋮---- A tuple with no non-finite float still round-trips through json as an array; return it unchanged to preserve the no-copy fast path. ⋮---- Patterns for code structure boundaries function/class/method definitions ⋮---- SQL top-level statement boundaries non-indented only ⋮---- Comment-section boundaries -- Section Header ⋮---- Try JSON key-aware truncation — only for config-like dicts all values are dicts ⋮---- Try section-aware truncation for markdown with headings ⋮---- Try code-structure-aware truncation function/class/SQL boundaries ⋮---- Try SQL/comment-section boundaries ⋮---- Repetitive con… Evidence: `src/memtomem_stm/proxy/compression.py`
- **Expected fallback: trace id is a best-effort correlation,** (source_file): logger = logging.getLogger name ⋮---- class CompressionFeedbackTracker ⋮---- @property def store self - CompressionFeedbackStore ⋮---- def close self - None ⋮---- resolved trace = trace id ⋮---- resolved trace = self. metrics store.lookup recent trace id ⋮---- Expected fallback: trace id is a best-effort correlation, not a hard requirement — the report still lands with trace id=None. Demoted from warning to avoid treating a benign metrics-store query failure as an actionable error. ⋮---- resolved trace = None ⋮---- def get stats self, tool: str None = None - dict Evidence: `src/memtomem_stm/proxy/compression_feedback.py`
- **Compression Feedback Store** (source_file): logger = logging.getLogger name ⋮---- TRACE LOOKUP WINDOW SECONDS: float = 1800.0 ⋮---- VALID KINDS: frozenset str = frozenset ⋮---- SCHEMA = """ ⋮---- def is valid kind kind: str - bool ⋮---- def valid kinds - list str ⋮---- class CompressionFeedbackStore ⋮---- def init self, db path: Path, retention days: int = 0 - None ⋮---- def initialize self - None ⋮---- db = sqlite3.connect str self. db path , check same thread=False ⋮---- cutoff = time.time - self. retention days 86400.0 deleted = db.execute ⋮---- def close self - None ⋮---- def get tool feedback summary self, since seconds: float = 86400.0 - dict str, dict ⋮---- cutoff = time.time - since seconds rows = self. db.execute result: dic… Evidence: `src/memtomem_stm/proxy/compression_feedback_store.py`
- **Timeout for a single LLM compression call. A slow or hung LLM endpoint** (source_file): logger = logging.getLogger name ⋮---- PROXY ENV PREFIX = "MEMTOMEM STM PROXY " ⋮---- def collect proxy env overrides environ: dict str, str None = None - dict str, Any ⋮---- env = environ if environ is not None else dict os.environ overrides: dict str, Any = {} ⋮---- path = p.lower for p in key len PROXY ENV PREFIX : .split " " if p ⋮---- cursor = overrides ⋮---- existing = cursor.get part ⋮---- existing = {} ⋮---- cursor = existing ⋮---- def deep merge base: dict str, Any , overrides: dict str, Any - dict str, Any ⋮---- out = dict base ⋮---- existing = out.get k ⋮---- implicated: set str = set ⋮---- def add leaves path: list str , subtree: dict str, Any - None ⋮---- stack: list tuple list… Evidence: `src/memtomem_stm/proxy/config.py`
- **Reset the cached snapshot first: start is a supported re-entry path** (source_file): NO RETRY CODES = {-32600, -32601, -32602, -32603} ⋮---- logger = logging.getLogger name ⋮---- TOOLGRAPH UNREACHABLE ERRORS: tuple type BaseException , ... = ⋮---- class ToolgraphStartupError RuntimeError ⋮---- @dataclass frozen=True, slots=True class ProxyToolInfo ⋮---- prefixed name: str description: str input schema: dict str, Any server: str original name: str annotations: Any = None ⋮---- @dataclass frozen=True, slots=True class ToolConfig ⋮---- compression: CompressionStrategy max chars: int llm: LLMCompressorConfig None auto index enabled: bool selective: SelectiveConfig None cleaning: CleaningConfig hybrid: HybridConfig None extraction enabled: bool = False progressive: ProgressiveCo… Evidence: `src/memtomem_stm/proxy/manager.py`
- **Pipeline Stages** (source_file): @dataclass frozen=True, slots=True class ShapePassthrough ⋮---- has non text: bool ⋮---- @dataclass frozen=True, slots=True class ShapedResponse ⋮---- original text: str non text content: list Any passthrough: ShapePassthrough None = None ⋮---- @dataclass frozen=True, slots=True class CompressionResult ⋮---- compressed: str surfaced: str compressed chars for metrics: int metrics strategy: str ratio violation: bool effective compression: CompressionStrategy progressive passthrough on error: bool surfacing on progressive ok: bool None surface error: str None compress ms: float surface ms: float ⋮---- selective store error: bool ⋮---- @dataclass frozen=True, slots=True class IndexResult ⋮----… Evidence: `src/memtomem_stm/proxy/pipeline_stages.py`
- **Pre-compute per-section TF heading-weighted** (source_file): logger = logging.getLogger name ⋮---- class RelevanceScorer Protocol ⋮---- def score sections self, query: str, sections: list tuple str, str - list float : ... ⋮---- class BM25Scorer ⋮---- TOKEN RE = re.compile SUFFIX RE = re.compile r" ing ed ly tion ness ment ies es s $" HEADING WEIGHT = 3.0 ⋮---- def init self, , k1: float = 1.5, b: float = 0.75 - None ⋮---- def score sections self, query: str, sections: list tuple str, str - list float ⋮---- query terms = self. tokenize query ⋮---- Pre-compute per-section TF heading-weighted doc tfs: list dict str, float = doc lens: list float = ⋮---- heading tokens = self. tokenize title body tokens = self. tokenize body tf: dict str, float = {} ⋮----… Evidence: `src/memtomem_stm/proxy/relevance.py`
- **Unknown upstream reasons still withhold fail-safe under a** (source_file): logger = logging.getLogger name ⋮---- REASON CONFIG HIDDEN = "config hidden" REASON PROFILE EXCLUDED = "profile excluded" REASON NAME OVERFLOW = "name overflow" REASON DUPLICATE NAME = "duplicate name" REASON SENSITIVE METADATA = "sensitive metadata" REASON UNHEALTHY = "unhealthy" ⋮---- REASON TOOLGRAPH NOT GRANTED = "toolgraph not granted" REASON TOOLGRAPH DENY VIOLATION = "toolgraph deny violation" REASON TOOLGRAPH DENY GOVERNED = "toolgraph deny governed" REASON TOOLGRAPH DRIFTED = "toolgraph drifted" REASON TOOLGRAPH AMBIGUOUS = "toolgraph ambiguous" REASON TOOLGRAPH UNMAPPED = "toolgraph unmapped" REASON TOOLGRAPH TOOL NOT FOUND = "toolgraph tool not found" ⋮---- REASON TOOLGRAPH REJEC… Evidence: `src/memtomem_stm/proxy/tool_eligibility.py`
- **Tool Relevance** (source_file): RANKER VERSION BM25 = "v1-bm25-tool-relevance" ⋮---- RANKER VERSION BM25 RISK = "v2-bm25-risk-penalty" ⋮---- RANKER VERSION BM25 GRAPH RISK = "v3-bm25-graph-risk-penalty" ⋮---- PENALTY SOURCE NONE = "none" PENALTY SOURCE REVIEW = "review" PENALTY SOURCE GRAPH = "graph" PENALTY SOURCE BOTH = "review+graph" ⋮---- MAX SCHEMA CHARS = 2000 ⋮---- MAX QUERY CHARS = 512 ⋮---- def compose risk penalty native: float, graph: float - float ⋮---- def penalty source native: float, graph: float - str ⋮---- def derive query arguments: dict str, Any None - tuple str, str None ⋮---- ctx = arguments.get " context query" ⋮---- parts = ⋮---- def candidate document info: ProxyToolInfo - tuple str, str ⋮---- sche… Evidence: `src/memtomem_stm/proxy/tool_relevance.py`
- **Best-effort: a runtime sqlite fault on the lookup database locked,** (source_file): logger = logging.getLogger name ⋮---- CREATE TABLE = """ ⋮---- CREATE INDEX = """ ⋮---- raw = f"{provider fp}\x00{agent id}\x00{profile}\x00{candidate hash}\x00{generation}" ⋮---- class GraphConsultCache ⋮---- """Cross-restart cache of a successful tool-graph consult's raw facts.""" ⋮---- def init self, db path: Path, max scopes: int = 64 - None ⋮---- @staticmethod def candidate hash refs: Iterable str - str ⋮---- """Order-independent hash of the candidate ref set.""" raw = json.dumps sorted refs , separators= ",", ":" ⋮---- @staticmethod def provider fingerprint config: ToolgraphConfig - str ⋮---- """Backend identity: command + args + sorted env keys . Keys only — never env values NEO4J PA… Evidence: `src/memtomem_stm/proxy/toolgraph_cache.py`
- **Shared state — populated only when proxy is enabled** (source_file): logger = logging.getLogger name ⋮---- HASHED QUERY PREVIEW RE = re.compile r"sha256: 0-9a-f {16}" """Exact shape of the opaque ID FeedbackStore.get stats passes through verbatim for rows persisted under persist query text=False 352 part 3 . Used by stm surfacing stats to decide whether to emit the hash-legend line. A raw query starting with sha256: e.g. a user-typed checksum search would be 80-char-clipped by the store but still carry the literal prefix; matching the full 23-char digest shape keeps the legend from misfiring on those rows.""" ⋮---- FLAT SCORE WARNING MIN SAMPLES = 10 """Minimum recorded scores before stm surfacing stats warns about a zero-variance score distribution 560 step… Evidence: `src/memtomem_stm/server.py`
- **Cache** (source_file): class SurfacingCache ⋮---- def init self, ttl: float = 60.0, max entries: int = 200 - None ⋮---- def get self, query: str - list Any None ⋮---- key = self. hash query entry = self. cache.get key ⋮---- def set self, query: str, results: list Any - None ⋮---- oldest key = next iter self. cache ⋮---- def clear self - int ⋮---- n = len self. cache ⋮---- @staticmethod def hash query: str - str Evidence: `src/memtomem_stm/surfacing/cache.py`
- **348: default flipped from "prepend" to "append" so the** (source_file): class ToolSurfacingConfig BaseModel ⋮---- enabled: bool = True query template: str = "" namespace: str None = None min score: float None = Field default=None, ge=0.0, le=1.0 """Per-tool override. Takes precedence over the auto-tuner when set, even if auto tune enabled=True .""" max results: int None = Field default=None, gt=0 ⋮---- class SurfacingConfig BaseModel ⋮---- """Proactive memory surfacing configuration. LTM access is always remote-only via the MCP protocol. The surfacing engine spawns or connects to a memtomem MCP server using the ltm mcp command / ltm mcp args settings below. """ ⋮---- feedback db path: Path = Path "~/.memtomem/stm feedback.db" ⋮---- ltm mcp transport: Literal "s… Evidence: `src/memtomem_stm/surfacing/config.py`
- **A semantic key whose value is an opaque id uuid/hex/bool is** (source_file): UUID RE = re.compile r"^ 0-9a-f {8}- 0-9a-f {4}- 0-9a-f {4}- 0-9a-f {4}- 0-9a-f {12}$", re.I HEX RE = re.compile r"^ 0-9a-f {24,}$", re.I SEMANTIC KEYS = {"query", "search", "path", "file", "url", "topic", "name", "title", "description"} PATH KEYS = {"path", "file", "filepath", "file path", "filename"} ⋮---- PATTERN KEYS = {"pattern", "glob"} ⋮---- class ContextExtractor ⋮---- tool cfg = config.context tools.get tool ⋮---- cq = arguments " context query" ⋮---- parts: list str = ⋮---- A semantic key whose value is an opaque id uuid/hex/bool is filtered here too — pre-fix only the free-text branch applied the identifier filter, so a semantic-keyed id leaked into the query inconsistent and a p… Evidence: `src/memtomem_stm/surfacing/context_extractor.py`
- **Gate has already recorded the specific reason internally. Avoid** (source_file): logger = logging.getLogger name ⋮---- QUERY HASH PREFIX = "sha256:" ⋮---- class SurfacingEngine ⋮---- @property def observability self - SurfacingObservability None ⋮---- def clear cache self - int ⋮---- def persistable query self, query: str - str ⋮---- @staticmethod def hashed query query: str - str ⋮---- digest = hashlib.sha256 query.encode "utf-8" .hexdigest :16 ⋮---- def active min score self, tool: str, , adjust auto tuner: bool - float ⋮---- """Return the score floor currently used for surfacing decisions.""" tool cfg = self. config.context tools.get tool ⋮---- @property def injection mode self - str ⋮---- """Formatter injection mode — "prepend" , "append" , or "section" . Read by Pr… Evidence: `src/memtomem_stm/surfacing/engine.py`
- **Resume tunings persisted from a previous process — without this** (source_file): logger = logging.getLogger name ⋮---- VALID RATINGS: tuple str, ... = ⋮---- class FeedbackTracker ⋮---- def init self, config: SurfacingConfig, db path: Path None = None - None ⋮---- resolved = db path if db path is not None else config.feedback db path.expanduser before = inspect feedback db resolved ⋮---- @property def store self - FeedbackStore ⋮---- def bootstrap status self - dict str, object ⋮---- def close self - None ⋮---- ok = self. store.record feedback surfacing id, rating, memory id ⋮---- class AutoTuner ⋮---- """Auto-adjust min score based on negative feedback ratios. Integrated into SurfacingEngine — when auto tune enabled=True and FeedbackTracker is available, the engine call… Evidence: `src/memtomem_stm/surfacing/feedback.py`
- **column missing fresh CREATE just ran with the relaxed schema, or** (source_file): logger = logging.getLogger name ⋮---- NEGATIVE FEEDBACK RATINGS = "not relevant", "already known" ⋮---- HASHED QUERY RE = re.compile r"sha256: 0-9a-f {16}" """Exact shape of the opaque ID written under SurfacingConfig.persist query text=False 352 part 3 : the literal prefix sha256: followed by 16 lowercase hex chars 23 chars total . Prefix-only matching would misclassify legitimate raw queries that happen to start with sha256: — e.g. a user-typed checksum search — and bypass the 80-char preview clip, leaking unbounded user-derived text. re.fullmatch against this pattern is the gate.""" ⋮---- SCHEMA = """ ⋮---- REQUIRED TABLES = tuple ⋮---- def relax surfacing events query notnull db: sqlite… Evidence: `src/memtomem_stm/surfacing/feedback_store.py`
- **350: surfacing id + rating spec live above the bullet list so they** (source_file): WORKING MEMORY HEADER = " Working Memory: " ⋮---- class SurfacingFormatter ⋮---- def init self, config: SurfacingConfig - None ⋮---- def relevance bucket self, score: float, score floor: float None = None - str ⋮---- floor = self. config.min score if score floor is None else score floor ⋮---- band = 1.0 - floor related start = floor + band / 3 strong start = floor + 2 band / 3 ⋮---- @staticmethod def format source source file: Any - str ⋮---- parts = getattr source file, "parts", None ⋮---- anchor = getattr source file, "anchor", "" path parts = part for part in parts if part and part != anchor ⋮---- def format namespace badge self, namespace: str None - str ⋮---- """Inject surfaced memorie… Evidence: `src/memtomem_stm/surfacing/formatter.py`
- **Preserve chunk id from core instead of sha256 content** (source_file): logger = logging.getLogger name ⋮---- SearchOutcome = Literal ⋮---- @dataclass class RemoteSearchResult ⋮---- class FakeMeta ⋮---- def init self, source: str, namespace: str ⋮---- class FakeChunk ⋮---- def init self, content: str, source: str, namespace: str ⋮---- def init self, content: str, score: float, source: str = "", namespace: str = "default" ⋮---- class ResultParser ⋮---- BLOCK SPLIT RE = re.compile r"^ ?=\ \d+\ \s+\d+\.?\d \s \ ", flags=re.MULTILINE HEADER RE = re.compile r"\ \d+ \ \s+ \d+\.?\d \s \ .+ " NS RE = re.compile r"\ ^\ + \ \s . " RANK SUFFIX RE = re.compile r"\s \ \d+/\d+\ \s $" FIRST TOKEN RE = re.compile r" \S+ " ⋮---- class CompactResultParser ResultParser ⋮---- """P… Evidence: `src/memtomem_stm/surfacing/mcp_client.py`
- **Explicit exclusions** (source_file): MAX RECENT QUERIES = 50 MAX SURFACING TIMESTAMPS = 200 RATE LIMIT WINDOW SECONDS = 60.0 SIMILARITY THRESHOLD = 0.95 ⋮---- class RelevanceGate ⋮---- full name = f"{server} {tool}" ⋮---- Explicit exclusions ⋮---- tool cfg = self. config.context tools.get tool ⋮---- now = time.monotonic ⋮---- def record surfacing self, query: str - None ⋮---- @staticmethod def jaccard similarity a: str, b: str - float ⋮---- tokens a = set a.lower .split tokens b = set b.lower .split ⋮---- intersection = tokens a & tokens b union = tokens a tokens b Evidence: `src/memtomem_stm/surfacing/relevance.py`
- **Changelog** (documentation): All notable changes will be documented in this file. Format: Keep a Changelog https://keepachangelog.com/en/1.1.0/ Evidence: `CHANGELOG.md`
- **memtomem Individual Contributor License Agreement** (documentation): memtomem Individual Contributor License Agreement Evidence: `CLA.md`
- **Hook golden fixtures are byte-exact compared via read bytes ; pin LF so a** (source_file): Hook golden fixtures are byte-exact compared via read bytes ; pin LF so a Windows checkout core.autocrlf=true can't CRLF-convert them and break the byte-identity assertion test kimi render then serialize golden raw stdout . The raw-stdout goldens are .txt; the JSON goldens are parsed structurally so are EOL-agnostic, but pinning the whole tree keeps future B2 host fixtures safe. tests/fixtures/hooks/ text eol=lf Evidence: `.gitattributes`
- **Python** (source_file): Python pycache / .py cod $py.class .egg-info/ .pytest cache/ .mypy cache/ .ruff cache/ Evidence: `.gitignore`
- **01 Quickstart Proxy Setup** (source_file): { "cells": { "cell type": "markdown", "id": "6ca0bb13", "metadata": {}, "source": " 01 — Quickstart: Proxy a tool through STM\n", "\n", "This notebook walks you through the minimum viable memtomem-stm\n", "setup: register one upstream MCP server, talk to STM as an MCP\n", "client, and read the proxy stats.\n", "\n", " You will learn: \n", "\n", "- How to register an upstream MCP server with the mms CLI\n", "- How STM exposes proxied tools namespaced with a prefix \n", "- How to call tools via the MCP Python client\n", "- How to read stm proxy stats to see what STM did\n", "\n", " Prereqs: uv sync installs the dev group including Jupyter .\n", "No external services required — we use a trivia… Evidence: `notebooks/01_quickstart_proxy_setup.ipynb`
- **---------------------------------------------------------------------------** (source_file): def repo root - Path ⋮---- cwd = Path.cwd .resolve ⋮---- def fixtures dir - Path ⋮---- """Return the absolute path to notebooks/ fixtures/.""" ⋮---- def fake ltm path - Path ⋮---- path = fixtures dir / "fake ltm.py" .resolve ⋮---- --------------------------------------------------------------------------- State isolation ⋮---- def isolate stm state prefix: str = "mms nb ", , enable surfacing: bool = False - Path ⋮---- tmp = Path tempfile.mkdtemp prefix=prefix config path = tmp / "stm proxy.json" ⋮---- def configure fake ltm - Path ⋮---- fake = fake ltm path ⋮---- @asynccontextmanager async def stm session - AsyncIterator ClientSession ⋮---- params = StdioServerParameters ⋮---- def extract t… Evidence: `notebooks/_helpers.py`
- **All three entry points resolve to the same Click group. The group's** (source_file): project name = "memtomem-stm" version = "0.1.31" description = "Short-term memory proxy gateway with proactive memory surfacing for AI agents" authors = {name = "DAPADA Inc.", email = "contact@dapada.co.kr"}, {name = "memtomem contributors"}, license = {text = "Apache-2.0"} keywords = "memory", "ai", "mcp", "proxy", "gateway", "agent", "caching", "compression" classifiers = "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: Apache Software License", "Programming Language :: Python :: 3.12", "Topic :: Scientific/Engineering :: Artificial Intelligence", "Topic :: Software Development :: Libraries :: Python Modules", readme = "README.md" requires-… Evidence: `pyproject.toml`

## Rules the Host AI Must Follow

- **Treat this asset as pre-work context, not a runtime environment.**: The AI Context Pack contains only an evidence-backed understanding of the project, not the project's executable state. Evidence: `README.md`, `notebooks/README.md`, `CLAUDE.md`
- **When answering the user, distinguish what can be previewed from what can only be verified after install.**: The consumer value of the pre-install experience comes from reducing bad installs and misjudgments, not from pretending to be a real run. Evidence: `README.md`, `notebooks/README.md`, `CLAUDE.md`

## Questions the User Should Answer First

- Which host AI or local environment do you plan to use it in?
- Do you just want to experience the workflow first, or are you ready to actually install?
- What matters most to you: install cost, output quality, or conflicts with your existing rules?

## Acceptance Checks

- Every capability claim can be traced back to a file path in evidence_refs.
- AI_CONTEXT_PACK.md does not package previews as a real run.
- The user can understand who it fits, what it can do, how to start, and the risk boundaries within 3 minutes.

---

## Doramagic Context Augmentation

The following sections strengthen the repository context for a host AI. Human Manual data is a reading route, and pitfall notes become operating constraints.

## Human Manual Outline

Usage rule: this is only a reading route and salience signal, not factual authority. Concrete claims must still return to repo evidence or Claim Graph.

Host AI hard rules:
- Do not treat page titles, section order, summaries, or importance values as factual project evidence.
- When explaining the Human Manual outline, state that it is only a reading route or salience signal.
- Capability, installation, compatibility, runtime state, and risk claims must cite repo evidence, source paths, or Claim Graph.

- **Introduction & System Architecture**: importance `high`
  - source_paths: README.md, src/memtomem_stm/server.py, src/memtomem_stm/proxy/manager.py, src/memtomem_stm/proxy/pipeline_stages.py
- **Proxy Pipeline: Clean, Compress, Cache**: importance `high`
  - source_paths: src/memtomem_stm/proxy/manager.py, src/memtomem_stm/proxy/cleaning.py, src/memtomem_stm/proxy/compression.py, src/memtomem_stm/proxy/cache.py, src/memtomem_stm/proxy/tool_eligibility.py
- **Memory Surfacing & LTM Integration**: importance `high`
  - source_paths: src/memtomem_stm/surfacing/engine.py, src/memtomem_stm/surfacing/relevance.py, src/memtomem_stm/surfacing/context_extractor.py, src/memtomem_stm/surfacing/formatter.py, src/memtomem_stm/surfacing/mcp_client.py
- **CLI, Configuration, Daemon & Known Limitations**: importance `high`
  - source_paths: src/memtomem_stm/cli/proxy.py, src/memtomem_stm/cli/daemon_cmd.py, src/memtomem_stm/cli/hook_cmd.py, src/memtomem_stm/cli/hook_adapter.py, src/memtomem_stm/cli/hook_hosts.py

## Repo Inspection Evidence

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `4dc2fa037e3d3a13d7e42959c51f042469dc5a42`
- inspected_files: `README.md`, `pyproject.toml`, `uv.lock`, `docs/caching.md`, `docs/cli.md`, `docs/compression.md`, `docs/configuration.md`, `docs/selection-telemetry.md`, `docs/surfacing.md`, `src/memtomem_stm/__init__.py`, `src/memtomem_stm/__main__.py`, `src/memtomem_stm/cli/__init__.py`, `src/memtomem_stm/cli/_write_lock.py`, `src/memtomem_stm/cli/daemon_cmd.py`, `src/memtomem_stm/cli/hook_adapter.py`, `src/memtomem_stm/cli/hook_cmd.py`, `src/memtomem_stm/cli/hook_hosts.py`, `src/memtomem_stm/cli/mms_host.py`, `src/memtomem_stm/cli/mms_import.py`, `src/memtomem_stm/cli/mms_project.py`

Host AI hard rules:
- Without repo_clone_verified=true, do not claim that the source code has been read.
- Without repo_inspection_verified=true, do not write README, docs, or package-file conclusions as facts.
- Without quick_start_verified=true, do not claim that the Quick Start path has run successfully.

## Doramagic Pitfall Constraints

These rules come from Doramagic discovery, validation, or compilation findings. The host AI must treat them as operating constraints, not background notes.

### Constraint 1: Security or permission risk requires verification

- Trigger: Developers should check this security_permissions risk before relying on the project: ci: supply-chain hardening — dependency audit, Dependabot, action SHA pinning, top-level workflow permissions
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: ci: supply-chain hardening — dependency audit, Dependabot, action SHA pinning, top-level workflow permissions. Context: Observed when using python
- Why it matters: Developers may expose sensitive permissions or credentials: ci: supply-chain hardening — dependency audit, Dependabot, action SHA pinning, top-level workflow permissions
- Evidence: failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/609
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 2: Security or permission risk requires verification

- Trigger: Developers should check this security_permissions risk before relying on the project: privacy: disabling privacy_scan_enabled silently sends raw upstream text to external LLM providers — warn loudly; consider entropy heuristic
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: privacy: disabling privacy_scan_enabled silently sends raw upstream text to external LLM providers — warn loudly; consider entropy heuristic. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may expose sensitive permissions or credentials: privacy: disabling privacy_scan_enabled silently sends raw upstream text to external LLM providers — warn loudly; consider entropy heuristic
- Evidence: failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/610
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 3: Security or permission risk requires verification

- Trigger: Developers should check this security_permissions risk before relying on the project: tests: fill direct-coverage gaps — observability/tracing, mms/secrets, mms/detect, cli/daemon_cmd, relevance embedding paths
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: tests: fill direct-coverage gaps — observability/tracing, mms/secrets, mms/detect, cli/daemon_cmd, relevance embedding paths. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may expose sensitive permissions or credentials: tests: fill direct-coverage gaps — observability/tracing, mms/secrets, mms/detect, cli/daemon_cmd, relevance embedding paths
- Evidence: failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/619
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 4: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: proxy: upstream call_tool path has no circuit breaker — SECURITY.md claims per-upstream breaker isolation
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: proxy: upstream call_tool path has no circuit breaker — SECURITY.md claims per-upstream breaker isolation. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may fail before the first successful local run: proxy: upstream call_tool path has no circuit breaker — SECURITY.md claims per-upstream breaker isolation
- Evidence: failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/608
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 5: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: v0.1.29
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.1.29. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: v0.1.29
- Evidence: failure_mode_cluster:github_release | https://github.com/memtomem/memtomem-stm/releases/tag/v0.1.29
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 6: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: Harden non-startup exc_info cleanup logs against credential leaks (follow-up to #580/#593)
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Harden non-startup exc_info cleanup logs against credential leaks (follow-up to #580/#593). Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may misconfigure credentials, environment, or host setup: Harden non-startup exc_info cleanup logs against credential leaks (follow-up to #580/#593)
- Evidence: failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/605
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.