centricmem-agent

# CentricMem Agent Skill **Names:** product/CLI = `centricmem`; GitHub install package = `centricmem-skill`; this Agent Skill folder = `centricmem-agent` (keep that folder name — it is not a second product). Handover (when / loop). Schemas win. Branches: [REFERENCE.md](REFERENCE.md). **Library** → **Shelf** → **Card** (summary + key points). No Inbox / `unclassified`. One key = grants. Never paste keys in chat (REFERENCE **Bearer: where plaintext is OK vs not** — claim may write a private local MCP file; docs/plans use `${VAR}` or URL-only). **Style** of a card (voice, length, evidence density) is yours + this agent's — not a CentricMem house voice. Structure only: REFERENCE **Card contract**. ## Do not (full list: REFERENCE) - Don't wait for "log this" / close / wrap up to file a finished chunk — sweep before you yield (§4) - Don't write `unclassified` — pick or create a named shelf - Don't put secrets / keys in cards, and never ask the human to paste a key or transcript in chat - Never echo a credential value. Confirm a key with a fingerprint, not the value (`9352... len=64 fp=5E4ED29C`); never dump `mcp.json` / `config.toml` / `*.env` whole, and never redact by length threshold (short keys slip through). If a key reaches the transcript, say so in that turn and rotate it. Details: REFERENCE **Never echo a credential (agent side)**. - Don't stop after a title-only card — every card needs summary + key points - Don't treat this git checkout as the memory disk - Don't let a dead session pass for a key problem: a transport failure gets the re-handshake path (section 0), and a refusal (401/403) gets the rotation path - different causes, different fixes, and never call a key unrotated from the store alone: compare three fingerprints first - the card, the process env, and whether this host is on OAuth at all. ## When to Use Start or resume; search; file Non-Micro; connect / refresh Skill. Recipes: REFERENCE. ## 0. Reach 1. MCP only `https://mem.centricmem.com/mcp`: `cm_health` `cm_ambient` `cm_doctor` `cm_search` `cm_show` `cm_note` `cm_log_decision` `cm_done` `cm_keep` `cm_library` `cm_copy` `cm_move` `cm_delete` `cm_rename` `cm_import` `cm_index` `cm_ops`. No curl / CLI-write / bootstrap. 2. Missing tools or short grants → **connect this turn**. REFERENCE **Reach**. Remote/cloud is **not** “paste key only”: OAuth if this agent receives the browser login; paste Bearer only when it cannot. Listed OAuth hosts only: an unlisted callback shape leaves the host stuck on “connecting”, so prefer `/connect?device=` and send that callback shape to zeyu@poppyg.com (REFERENCE “Approved, but the agent stays connecting”). Tools that were there and then vanished, or a load-time `discover` failure, mean the MCP **session** died, not the key: probe with `centricmem doctor` (its own request, unaffected by the session), re-handshake (goose: disable then enable centricmem, or restart the host), retry once. While the session is dead, nothing here is loaded either. 3. `cm_show` = card on the **hosted** shelf (not a local junction file). `grants=["*"]` = default. Extra `mode=read` = view-only (search/show only). `ACADEMIC.md` beside this → follow it. Upsert corpus paths: REFERENCE **Import shapes** (`bundle.imported` + `rel_path`, never bare `items=`). Host-specific install, refresh or failure detail: `cm_ops` - read it when a host detail actually blocks you (librarian >=1.0.6; it is served on request rather than shipped in every copy). 4. **Writes — `items=` and `bundle` are different contracts.** `cm_note` / `cm_log_decision` / `cm_done` file cards; `cm_import` with `items=` (or `package.items`, or a zip) adds **new cards under `imported/kept/`** and nothing else. `cm_import` with **`bundle: {version: 1, …}`** is the full ImportBundle and **also writes library files**: `context` → the shelf's **`active_context.md`** (current focus, overwritten), `rules` → **`AGENTS.md` Global Rules**, plus `decisions` / `lessons` / `sessions` / `imported` / `research`. A key that can open the shelf can write those — it is **not** host-only. An unknown or mistyped top-level slot is **`400 BAD_IMPORT_BUNDLE`** (it names the slot and the allowed list), never a silent drop. Slot table: REFERENCE **Writes**. ## 1. Classify | Skip (Micro) | Sweep (Non-Micro) | |---|---| | Typo, one-liner, no durable fact | Implement, ops, research, architecture, decision | | | ≥2 real turns **or** one turn that shipped / decided | ## 2. Start Prefer `cm_ambient` with **`shelf=`** (or `library=`) first — it already carries grants / mode / skill_latest / Recent / Session. That shapes **Recent decisions / Session tail / Curate**, not only later write routing. Ambient with only an unmatched `cwd` and no `shelf=` often shows empty Recent/Session — that is not “the shelf is empty.” Call `cm_health` only when tools are missing, connect is needed, or ambient is unhealthy / unreachable. Unreachable: say once — no bootstrap. Named shelf for writes. **Resume = new session.** Compress, checkpoint restore, or new chat on same task → ambient first (health only if needed). Once after ambient (or health): refresh if `skill_latest` newer. **Load path ≠ refresh path** — read the version of the copy **this host loads**, not a sibling skills dir (plugin-tree hosts: `<host-plugins-dir>/centricmem-skill/package.json`; npx `-g` / `~/.agents` does not update that tree). Install morphologies + hosts outside them: REFERENCE Skill refresh — adapt, do not invent a fourth shared hub. After a disk refresh: **re-read this SKILL.md and Do not** before the next write — installing newer ≠ acting on it. Name the key once (`mode=read` → view-only). Don't log → skip sweep. Empty shelf once: REFERENCE Existing memory ## 3. During **chunk** = accepted unit (verified fragment, locked decision, evidenced lesson, delivery). Any in this reply → same-turn sweep. Not the whole task. **yield** = any reply end (incl. progress). Search/show/ambient while working. Hold half-finished. **Chunk done → sweep before you yield.** Cards need summary + key points. Keep stubs ≠ cards. File/folder: REFERENCE Writes. Voice/density: theirs + yours (REFERENCE **Card contract**), not a CentricMem template. ## 4. Sweep — single source No wrap-up wait. Agent close does not run this. Don't log / Skill done → skip. **Gate:** Non-Micro chunk this reply, zero `cm_*` this session, no Don't log → **sweep before you yield**. | File now | File at wrap-up | |---|---| | Locked decision; method-changing lesson; finished chunk | Version-tied stats; unverified conclusions | Same `lessons.md` title → 409; rewrite = `cm_delete` then write (REFERENCE). Early wrong write costs more. MCP down: hold **CentricMem deferred sweep**; connect (REFERENCE); file after health. Say so once, keep working without memory, and never fake a card, pick a local hub, or treat a leftover copy of the hub as the shelf. `shelf=` / `library=` (REFERENCE **Shelf routing**): 1. Transcript plaintext exists → Shell-read → `cm_keep` (no paste / `path=`). Else skip keep. 2. Same batch: `cm_note` / `cm_log_decision` / `cm_done` (+ `attach`) as needed. 3. Copy/move/delete/rename leftovers: REFERENCE Writes. ## Typical Workflows Connect: REFERENCE. **Daily:** §2 → work → §4 before yield. Empty shelf: REFERENCE Existing memory.