---
title: "Oh My Pi Memory Workbook"
description: "Complete OMP memory tutorial with five fictional stories, configuration, lifecycle, verification checks, privacy warnings and the browser agent interface."
canonical: "https://present-sketch-tp94.here.now/labs/memory"
last-updated: "2026-08-29"
---

# Oh My Pi Memory Workbook

[Back to the complete Oh My Pi Workbook](/) · [Open the original interactive Memory lab](/labs/memory)

This is the preserved Memory lab edition, not the complete combined book. Its five stories and simulator are fictional. Only the interactive lab at `/labs/memory` exposes `window.memoryTutorial` version 1; the unified reading pages expose the separate `window.ompWorkbook` interface. The lab retains its original `omp-memory-workbook:checklist:v1` browser-local lesson flags. Neither interface accesses OMP or real memories.

Keep what matters. Recall it later.

[Interactive workbook](https://present-sketch-tp94.here.now/labs/memory) · [About](https://present-sketch-tp94.here.now/about) · [Contact and feedback](https://present-sketch-tp94.here.now/contact) · [Privacy](https://present-sketch-tp94.here.now/privacy) · [Agent index](https://present-sketch-tp94.here.now/llms.txt) · [Sitemap](https://present-sketch-tp94.here.now/sitemap.xml) · [Crawler policy](https://present-sketch-tp94.here.now/robots.txt)

This independent tutorial is a companion to an OMP session, not a connection to it. It teaches a sanitized configuration snapshot dated **28 August 2026**, not the live state of your installation. Every story and the Cedar project are fictional. No private memories, transcripts, credentials or authentication data are included. This is not official OMP support or a company website.

## Start with a read, not a setting change

Your current conversation is OMP’s working context. Durable memory is information it can retrieve in a later session. Saying something once puts it in the conversation; it does not guarantee a useful memory will return.

Open OMP in your usual project directory and ask the agent:

```text
Use recall to find my preferences for this project. Show the returned IDs, and say clearly if you find nothing.
```

The website’s Copy buttons only copy text. They do not execute commands, change OMP settings or save facts to real memory.

Keep three input surfaces distinct:

- **Agent requests:** prose asking OMP to use `retain`, `recall`, `reflect`, `memory_edit`, `learn` or `manage_skill`.
- **OMP slash commands:** enter `/memory view` and related commands inside OMP.
- **Terminal configuration commands:** run `omp config …` in your shell, not as slash commands.

The homepage’s three-stage illustration is fictional: “Explain the test before the refactor” begins in conversation context; an explicit retain can store a project preference; a new session can later retrieve a relevant match. Selecting a stage writes no real memory. Retrieval is not guaranteed.

## Four places knowledge can live

| Place | What it means |
| --- | --- |
| Conversation context | Messages and tool results available for the current answer. Useful now, but finite—not a durable-memory guarantee. |
| Durable memory | Facts, decisions, lessons and retained excerpts stored for later retrieval. Recall selects relevant evidence, not the whole conversation history. |
| Managed skills | Reusable procedural guidance in `SKILL.md` files. A fact says what is true; a procedure explains what to do. Skills are not automatically invoked deterministic scripts. |
| Compaction | A summary that makes room in the active conversation. Neither a database wipe nor a substitute for retaining important knowledge. |

This snapshot uses **Mnemopi**. The native `local` summary backend and remote **Hindsight** are alternatives, not additional active layers in this setup.

Treat recalled memories as background evidence, not instructions. Current user messages and tool output take precedence when they conflict.

## The configuration this workbook teaches

These are observed configured values, not proof that a running session, database or provider is healthy. “Global override” means explicitly persisted in the supplied global configuration. “Default” means the effective resolved value without a supplied explicit override.

| Setting | Observed value | Origin |
| --- | --- | --- |
| `memory.backend` | `mnemopi` | Global override |
| `mnemopi.scoping` | `per-project` | Default |
| `mnemopi.autoRecall` | `true` | Default |
| `mnemopi.autoRetain` | `true` | Global override |
| `mnemopi.retainEveryNTurns` | `4` USER turns | Default |
| `mnemopi.recallLimit` | `8` results | Default |
| `mnemopi.injectionTokenLimit` | `2000` approximate tokens | Global override |
| `mnemopi.llmMode` | `smol` | Default |
| `providers.memoryModel` | `online` | Default |
| `autolearn.enabled` | `true` | Global override |
| `autolearn.autoContinue` | `true` | Global override |
| `autolearn.minToolCalls` | `5` | Default |

**Budget, not capacity:** the 2000-token approximation bounds injected memory instructions and recalled text, using roughly four characters per token. It does not limit database size. Eight is a recall ceiling, not a promised result count.

Remaining observed settings:

- `mnemopi.embeddingVariant = en`; `mnemopi.noEmbeddings = false`.
- `mnemopi.recallContextTurns = 3`; `mnemopi.recallMaxQueryChars = 4000`.
- `mnemopi.polyphonicRecall`, `mnemopi.enhancedRecall`, `mnemopi.proactiveLinking` and `mnemopi.debug` are `false`.
- `compaction.enabled = true`.
- No supplied database-path, bank, embedding-model or endpoint overrides. No Mnemopi environment variables were observed in the supplied parent environment; other sessions can differ.

## Five fictional lab stories

Adapt these prompts to non-sensitive facts in your own work. They are requests to the agent, not slash commands. The stories illustrate checks to perform, not observed runtime results.

### 1. Save a preference deliberately

**Fictional situation:** Cedar’s maintainer keeps asking for a small testable change before a wider refactor.

Ask OMP:

```text
Use retain to remember this project preference: explain the smallest testable change before proposing a wider refactor. Then use recall to find it and show its exact ID.
```

`retain` requests a save immediately; it does not wait for the four-turn batch. A preference saved here is project-scoped, not automatically universal.

**Check:** recall returns the intended preference and an ID. Try again in a fresh session from the same directory.

**Pitfall:** the retain acknowledgement counts requested items. It alone is not proof of a successful write.

### 2. Resume the reason, not just the task

**Fictional situation:** a new session starts after Cedar’s queue-design discussion. You remember the decision, but not its constraints.

Ask OMP:

```text
Use recall to find Cedar's durable job-queue decision, rejected alternatives and migration constraints. Show the returned IDs. Separate saved evidence from assumptions before proposing next steps.
```

The first prompt can trigger automatic recall. Ask for on-demand `recall` later when the topic changes.

**Check:** look for the decision’s rationale, source and date—not merely a confident summary.

**Pitfall:** “No relevant memories found” does not mean the entire store is empty. Try specific project and decision terms.

### 3. Connect related lessons

**Fictional situation:** Cedar has several retry and timeout decisions. You want the pattern, including disagreements.

Ask OMP:

```text
Use reflect to examine Cedar's retry and timeout decisions. Compare their tradeoffs; distinguish agreement, conflict and missing evidence. Use recall for IDs when checking a source.
```

Here, `reflect` retrieves and formats scoped memories for the agent to synthesize. It is not a separate guaranteed reasoning service or an exhaustive database audit.

**Check:** the answer distinguishes retrieved evidence from the agent’s interpretation.

**Pitfall:** a fluent synthesis can still omit relevant memories. The recall limit still applies.

### 4. Correct the row, not the preview

**Fictional situation:** Cedar’s agreed retry limit changed from three to five. An old memory still says three.

Begin with inspection, without editing:

```text
Recall Cedar's retry-limit decision and show exact IDs. Read each candidate's memory:// address in full, including its bank and store. Do not edit yet. Identify the row that says three retries.
```

Ask OMP to read `memory://` followed by an **exact returned ID**. That is OMP’s internal resource address, not an HTTP endpoint on this website. It reveals full content and metadata; a recall preview can be clipped.

After selecting the working-store row, ask:

```text
Use memory_edit update on the exact working-store ID we just selected. Replace only the three-retry rule with five retries, preserving the rest of its full content. Read back that same ID, then recall the topic again.
```

Store rules in this snapshot:

- `update` and `forget` operate on working rows. To remove an unwanted row, ask OMP to forget the exact selected ID.
- `invalidate` supports working or episodic rows. Ask OMP to invalidate the selected ID, optionally linking a verified replacement ID.
- Extracted `fact` projections are read-only: expect `not_editable`, not an edit.

**Check:** inspect the operation’s returned status, bank and store. Verify the full row and related recall results afterward.

**Pitfall:** an update replaces content wholesale. Never reconstruct it from a clipped preview. Episodic update/forget can report `not_found`; stale copies may remain elsewhere. Forgetting one eligible row is not universal erasure.

### 5. Turn a verified fix into a technique

**Fictional situation:** a duplicate-delivery test failed before Cedar’s fix and passed afterward. Now there is a lesson worth keeping.

Ask OMP:

```text
We verified Cedar's duplicate-delivery fix with a failing test before the fix and a passing rerun afterward. Use learn to capture the cause, fix, limits and verification. If the steps generalize, also create a managed skill named webhook-replay-check with prerequisites, steps and failure checks. Exclude credentials.
```

`learn` stores a lesson and can also write a skill. `manage_skill` creates, updates or deletes managed skills separately. Generated files live in the `managed-skills` directory under OMP’s agent configuration directory, separate from authored `skills`; authored names take precedence.

**Check:** recall the lesson and inspect `managed-skills/webhook-replay-check/SKILL.md` under that configuration directory. If discovery lags, start a fresh session.

**Pitfall:** verify your own technique first. Skill creation can fail after the lesson is saved; check both outcomes. The example’s claimed before/after test evidence is fictional, not evidence for your project.

## The automatic lifecycle

1. **First turn:** automatic recall uses the first non-empty prompt and recent context. It is **not a new search every turn**; later prompt rebuilds can reuse the cached snippet. Request recall when needed.
2. **Four USER turns:** at agent-end, automatic retention checks for at least four new user turns since the retention cursor. It batches the unretained suffix—not four assistant replies or tool calls.
3. **Before compaction:** a fresh recall supplies additional context to the compaction summary. This is distinct from the first-turn recall gate.
4. **On shutdown:** best-effort disposal retains the remaining transcript and drains pending extraction, skipping fresh extraction and full consolidation. Shutdown deadlines can interrupt completion.

### A separate loop: auto-learn

With both autolearn switches on, an eligible completed top-level turn with **at least five tool calls** can trigger an extra private capture turn. Counts do not accumulate across prompts. Aborted turns, plan mode and goal-mode turns are skipped. This adds model use; it is not `autoRetain` and does not run after every prompt.

## The command desk

Enter these slash commands inside OMP. Nothing on this website executes them.

| Command | Meaning and limits |
| --- | --- |
| `/memory view` | Shows the injected payload: instructions plus cached recalled text, not the whole database or a fresh search. |
| `/memory stats` | Shows scoped bank counts, working/episodic memory, triples and database locations. Use it to understand scope. |
| `/memory diagnose` | Inspects scoped database diagnostics and integrity findings. Does not establish provider authentication or embedding availability. |
| `/memory enqueue` | **Mutates memory.** Alias: `/memory rebuild`. Retains the remainder, flushes extraction and requests full, age-gated cross-session consolidation—not an index-only rebuild. An “enqueued” banner is not proof of success; check diagnostics and recall afterward. |

### Destructive warning: clear is a wipe, not a refresh

`/memory clear` and `/memory reset` delete all currently scoped database files and sidecars, including rescued legacy banks and shared/base databases when present—even beyond ordinary per-project recall. **The controller described in this snapshot has no confirmation.** Inspect scope and backups first. Removal can fail; a success banner does not prove erasure.

`/memory mm` is Hindsight-only, not a Mnemopi command workflow.

### Optional configuration changes—not applied by this tutorial

Use your shell, not OMP’s prompt. Read a value first:

```sh
omp config get mnemopi.autoRetain --json
```

Choose individual changes deliberately; this is not a script to run wholesale.

| Goal | Shell command | Caveat |
| --- | --- | --- |
| Pause periodic retention only | `omp config set mnemopi.autoRetain false` | Not a complete privacy switch; other save paths remain. |
| Skip extra capture turns | `omp config set autolearn.autoContinue false` | Standing auto-learn guidance remains. |
| Disable the active memory backend | `omp config set memory.backend off` | Does not delete existing data. |
| Disable auto-learn separately | `omp config set autolearn.enabled false` | Also disables its generated-skill tools on fresh startup. |

Read back changed keys with `omp config get` and `--json`. Start a fresh OMP session after changes affecting startup tools or the backend.

## Privacy and costs

### In a real OMP session

Mnemopi uses local SQLite and local embedding execution. Initial embedding-model downloads may use the network. With `providers.memoryModel = online`, retained user excerpts can reach the tiny/smol role for fact extraction, and consolidation can use that online model too.

The snapshot’s configured global smol role is `google-antigravity/gemini-3.7-flash:medium`, with no TINY override. Actual runtime model resolution and authentication were not exercised. Recalled memories also enter the main model’s context. Budget for extraction, consolidation and extra capture turns; do not assume zero egress or guaranteed encryption.

**Automation switches are separate.** Turning `autoRetain` off gates periodic batches—not explicit saves, `learn`, enqueue or shutdown retention. Setting `memory.backend` to `off` disables the active backend, but does not delete data or stop normal main-model conversation/session persistence. Disable autolearn separately for generated skills.

**Forgetting is not universal erasure.** An eligible row can be deleted without erasing transcripts, backups, provider copies, skills or every derivative. Keep secrets out of memory; verify corrections instead of assuming all copies disappeared.

### On this website

The interactive homepage stores only self-reported checklist flags in the browser’s localStorage key `omp-memory-workbook:checklist:v1`. Reset lesson ticks removes that key; it does not touch OMP data. Storage can fail, and saved status is the last local observation, not a multi-tab guarantee. Copy controls attempt to write a displayed prompt or command to the clipboard; manual selection is the fallback. They do not read your clipboard or execute the copied text.

Fonts are self-hosted. The tutorial script makes no network requests, but loading public pages and fonts requires delivery through here.now and the read-only Cloudflare delivery layer. That layer does not add a tutorial datastore. This workbook does not establish what access logs the hosting providers keep or who can access them. No account, authentication, payment or local OMP connection is offered. See the [privacy explanation](https://present-sketch-tp94.here.now/privacy) for the distinction between site behavior and real memory processing.

## Troubleshooting

### Different session, different results?

Check the directory and bank first. `per-project` derives its bank from **resolved cwd, not git root**. Subdirectories and moved projects can differ. Same-cwd legacy rescue may add recall banks. Compare scoped stats and diagnostics.

### Rows exist, but the payload lacks them?

`/memory view` shows current injection, not stored coverage. Ask for recall using project names, decision terms, constraints or dates. An empty search differs from a backend-unavailable error.

### A recent conversation was not retained?

Count new USER turns against the four-turn threshold. For an important fact, request explicit retain and verify retrieval. Do not depend on shutdown finishing.

### Settings say “on,” but tools or recall fail?

Persisted settings can differ from running state. Start a fresh session. Check `/memory diagnose`, then embedding download/worker availability and memory-model availability. Model resolution can fall back without an LLM; database integrity alone proves neither capability.

### An old answer keeps coming back?

Inspect exact IDs, banks and stores. Check duplicates, rescued banks, read-only fact projections and cached injection. State the current correction explicitly; current user/tool evidence wins. Re-read and recall after editing rather than deleting vaguely matching rows.

## Your checkpoint

Mark these only after your own checks. Homepage ticks are self-reported lesson progress, not OMP verification or real memory state.

- [ ] I can distinguish context, memory and skills.
- [ ] I saved a non-sensitive fact and recalled its ID in a new session.
- [ ] I inspected full content before choosing an edit.
- [ ] I checked my bank scope and understand the automation switches.

The homepage is readable without JavaScript. Without it, select prompt text manually; the illustration remains readable and lesson ticks cannot be saved.

## Browser agent interface

### When to use—and when not to

Use the interface to read authored chapters, navigate the workbook, select the fictional illustration, open disclosures, inspect tutorial state or operate an explicitly requested local lesson checklist. Do not use it to search, save, correct or erase actual OMP memories, run terminal commands, authenticate to OMP or establish database health. No REST endpoint or MCP service is provided by this site.

Open the [canonical homepage](https://present-sketch-tp94.here.now/labs/memory) in a JavaScript-capable browser and evaluate in the **page’s main JavaScript world**. The API is `window.memoryTutorial`, version 1. A fetch-only document reader, an isolated extension world or a support page does not expose this object. If it is absent, use the authored Markdown for reading; do not invent a network API.

Call `discover()` for the live schemas, permissions, exact control IDs, enabled states and gaps. These schemas, not guesses from visible labels, define the currently loaded page’s interface.

| Operation | Input | Result |
| --- | --- | --- |
| `discover()` | None | Scope, permissions, schemas, controls and gaps. |
| `inspect()` | None | Authoritative page revision, content revision, current chapter, illustration, checklist/storage, clipboard, disclosures and stable controls. |
| `query({text, limit})` | Text of at most 240 characters; optional integer limit 1–10, default 5. | Searches authored chapter text, including closed disclosures, never memories. Status is `matched`, `empty` or `empty-query`; unavailable content is a structured failure. |
| `act({id, action, expectedRevision, …})` | Exact registered control ID, supported action and a fresh revision. | `performed` or `unchanged`, `changed`, current revision and optional clipboard outcome. |
| `wait({afterRevision, timeoutMs, match})` | Existing revision from this document; optional integer 0–5000 milliseconds, default 1500; optional `match` with `chapterId` and/or `demoStep` (1, 2 or 3). | `matched` only after a newer revision satisfying every supplied condition, otherwise `timed-out`; includes current revision and state. |
| `diagnose()` | None | Tutorial runtime, storage, clipboard capabilities and control integrity—not OMP health. |

`query()` matches all whitespace-separated search terms case-insensitively within a chapter. Results have a chapter ID, title, anchor, navigation control ID and excerpt. A chapter excerpt is not the full source text.

### Read, act, observe

Run this JavaScript in the homepage’s main world. It selects only a fictional stage:

```js
const t = window.memoryTutorial;
const capabilities = t.discover();
const chapters = t.query({ text: "compaction", limit: 3 });
const before = t.inspect();
const result = await t.act({
  id: "demo-recall",
  action: "click",
  expectedRevision: before.revision
});
const observed = result.ok && result.changed
  ? await t.wait({
      afterRevision: before.revision,
      timeoutMs: 1000,
      match: { demoStep: 3 }
    })
  : t.inspect();
const diagnostics = t.diagnose();
```

An already selected stage or another unchanged action does not guarantee a newer revision. Do not interpret a wait timeout as a successful transition, or a successful stage selection as a successful real memory operation.

### Action shapes and revision rules

- Use `action: "click"` for a discovered click control, such as a navigation, illustration, copy or reset control.
- Use `action: "setChecked"` with a boolean `checked` only for a checkbox control. This changes self-reported local progress, not verified OMP state. Do not tick it without the reader’s actual completion or explicit request.
- Use `action: "setOpen"` with a boolean `open` only for a disclosure’s **summary control ID**, such as `settings-extra-toggle`, not its containing details ID.
- Supply `checked` only for `setChecked`, and `open` only for `setOpen`. Extra or unsupported fields are rejected.
- Inspect immediately before every action. Pass that response’s opaque `revision` as `expectedRevision`; do not use `contentRevision` or manufacture a token.
- Revisions expire on reload. User actions, scrolling and asynchronous clipboard results can change them. On `STALE_REVISION`, inspect again and reassess the intended action.
- Honor `enabled` and `unavailableReason`. Disabled, hidden, inert or closed-disclosure targets are not actionable. Open the appropriate discovered disclosure first, then inspect again. Never bypass a disabled control by editing the DOM.
- Actions use the same native click/change paths as human controls. A structured success is not permission to claim unobserved effects.

For example, open the configuration disclosure without changing a setting:

```js
const t = window.memoryTutorial;
const before = t.inspect();
await t.act({
  id: "config-options-toggle",
  action: "setOpen",
  open: true,
  expectedRevision: before.revision
});
```

### Failures and boundaries

Failures use `{ok:false, error:{code,message}}`, with revision/scope metadata and optional details. The discovery schema lists `INVALID_ARGUMENT`, `STALE_REVISION`, `STALE_DOCUMENT`, `INVALID_REVISION`, `UNKNOWN_TARGET`, `AMBIGUOUS_TARGET`, `DISABLED_TARGET`, `UNSUPPORTED_ACTION`, `ACTION_FAILED`, `UNAVAILABLE` and `BUSY`.

Clipboard access depends on browser policy and user activation. Inspect the returned outcome; copying may require manual selection. A timed-out attempt is unconfirmed, not proof that a later browser write is impossible. Saved checklist state reports the last local observation, without multi-tab locking.

The API requires no login, API key, authentication or payment. It operates the tutorial only: no OMP, filesystem, credentials, real memories, command execution or network requests from its script. `diagnose()` cannot assess your OMP installation.

## Sources, method and limitations

The original workbook was AI-authored by Ultima from supplied sanitized configuration and OMP-facing source. Its factual review is source-based, not a live memory audit or a claim of human certification. This Markdown edition derives from the authored homepage and its browser API implementation. The configuration was observed with `omp config list --json`; the supplied record is 29 August 2026 at 00:01 UTC, while the workbook snapshot is dated 28 August. Memory contents and database health were not inspected.

This describes a custom local build, not guaranteed upstream version parity. Core extraction/consolidation internals were not exhaustively supplied. Examples describe expected checks rather than observed outcomes. The [upstream Oh My Pi project](https://github.com/can1357/oh-my-pi) is the place to consult public software documentation; it is not the operator or official support channel for this independent workbook.

Implementation references below are source-relative paths under `packages/coding-agent/src/`, not private filesystem links:

| Source | Relevant symbols |
| --- | --- |
| `mnemopi/config.ts` | `loadMnemopiConfig`, `computeMnemopiBankScope`, `projectBank`, `extendRecallWithLegacyBanks`, `truncateApproxTokens` |
| `mnemopi/state.ts` | `MnemopiSessionState`: `beforeAgentStartPrompt`, `maybeRetainOnAgentEnd`, `recallForCompaction`, `consolidate`, `dispose`, `getScopedMemory`, `editScopedMemory`; `getMnemopiScopedDbPaths` |
| `mnemopi/backend.ts` | `mnemopiBackend`, `resolveMnemopiProviderOptions`, `resolveMemoryCompletionInput` |
| `tools/memory-recall.ts`, `tools/memory-retain.ts`, `tools/memory-reflect.ts`, `tools/memory-edit.ts` | `MemoryRecallTool`, `MemoryRetainTool`, `MemoryReflectTool`, `MemoryEditTool` |
| `internal-urls/memory-protocol.ts` | `MemoryProtocolHandler.resolve`, `renderMnemopiMemory` |
| `autolearn/controller.ts`, `autolearn/managed-skills.ts` | `AutoLearnController`, `buildAutoLearnInstructions`, `writeManagedSkill`, `getManagedSkillsDir` |
| `tools/learn.ts`, `tools/manage-skill.ts` | `LearnTool`, `ManageSkillTool` |
| `memory-backend/types.ts`, `memory-backend/off-backend.ts` | `MemoryBackend`, `offBackend` |
| `modes/controllers/command-controller.ts` | `handleMemoryCommand` |

Reading fonts are served with the site under the SIL Open Font License. No telemetry or account connection is included in the tutorial script.

[Return to the interactive workbook](https://present-sketch-tp94.here.now/labs/memory) · [About](https://present-sketch-tp94.here.now/about) · [Contact and feedback](https://present-sketch-tp94.here.now/contact) · [Privacy](https://present-sketch-tp94.here.now/privacy) · [Agent index](https://present-sketch-tp94.here.now/llms.txt) · [Sitemap](https://present-sketch-tp94.here.now/sitemap.xml) · [Crawler policy](https://present-sketch-tp94.here.now/robots.txt)