Mnemopi memory backend

English | 中文 Oh My Pi can use @musepi/pi-mnemopi as a local long-term memory backend.

Set:

memory:
  backend: mnemopi

Example:

memory:
  backend: mnemopi
mnemopi:
  scoping: per-project-tagged

With this backend enabled, the coding agent:

1. Opens one or more local Mnemopi SQLite databases according to the configured bank scoping.
2. Recalls relevant memories into a <memories> block for the first model turn of a session and refreshes the base prompt if recall happens from the agent_start listener.
3. Retains completed conversation turns into the retain bank after agent turns, no more often than mnemopi.retainEveryNTurns.
4. Adds recalled memory as extra compaction context when compaction asks the memory backend for preCompactionContext.
5. Uses the normal /memory view, /memory stats, /memory diagnose, /memory clear, and /memory enqueue commands through the shared memory backend interface.

Recalled memory is background context, not instructions. Current user messages and tool output take precedence when they conflict.

Settings

Scoping

The coding-agent wrapper applies scoping on top of the underlying Mnemopi package:

• global uses one shared bank for recall and writes.
• per-project writes to and recalls from a bank derived from the current working directory alone — its basename plus a stable hash of its absolute path, independent of the surrounding git layout.
• per-project-tagged writes to the project-local bank and recalls from both the project-local bank and the shared global bank, with duplicate recall results merged.

The combined project-plus-global behavior lives in the wrapper. The @musepi/pi-mnemopi package itself still exposes banks and constructor options directly, including bank for selecting a bank name. Project-local banks other than the shared bank are stored as sibling bank databases managed by Mnemopi’s BankManager.

LLM and embeddings

The backend passes these settings to the Mnemopi constructor; if a setting is omitted, Mnemopi falls back to its MNEMOPI_* environment defaults. The backend does not download or run a local GGUF LLM. LLM-dependent paths use a configured pi-ai model, an opt-in local on-device memory model (providers.memoryModel, ONNX — overrides smol/remote when set to a local model), a dynamic completion function, a remote OpenAI-compatible endpoint, or deterministic no-LLM fallbacks.

FTS-only:

memory:
  backend: mnemopi
mnemopi:
  noEmbeddings: true

Equivalent constructor shape:

new Mnemopi({ noEmbeddings: true });

Remote embeddings:

mnemopi:
  embeddingModel: text-embedding-3-small
  embeddingApiUrl: https://api.openai.com/v1
  embeddingApiKey: ${OPENAI_API_KEY}

Equivalent constructor shape:

new Mnemopi({
  embeddingModel: "text-embedding-3-small",
  embeddingApiUrl: "https://api.openai.com/v1",
  embeddingApiKey,
});

Remote LLM:

mnemopi:
  llmMode: remote
  llmBaseUrl: https://api.openai.com/v1
  llmApiKey: ${OPENAI_API_KEY}
  llmModel: gpt-4.1-mini

Equivalent constructor shapes:

new Mnemopi({ llm: { baseUrl, apiKey, model } });
new Mnemopi({ llmBaseUrl: baseUrl, llmApiKey: apiKey, llmModel: model });

Dynamic function LLM for rotating OAuth tokens:

new Mnemopi({
  llm: async (prompt, opts) => {
    const token = await getFreshOauthToken();
    return await completeWithPiAi(prompt, {
      token,
      maxTokens: opts?.maxTokens,
      temperature: opts?.temperature,
    });
  },
});

pi-ai smol model LLM:

mnemopi:
  llmMode: smol

The coding agent resolves its configured smol role and passes a dynamic completion function so every Mnemopi LLM call can fetch the current provider credentials at call time:

new Mnemopi({
  llm: async (prompt, opts) => completeSmolWithCurrentAuth(prompt, opts),
});

Operational notes

• The default shared database lives under the agent memories directory in mnemopi/mnemopi.db; project-scoped banks use sibling database paths under that Mnemopi directory.
• /memory clear removes every scoped Mnemopi SQLite database and sidecar WAL/SHM files for the active configuration.
• /memory enqueue forces retention of the current session, flushes pending fact extractions, and runs Mnemopi sleep/consolidation.
• /memory stats and /memory diagnose render backend-specific bank statistics/diagnostics when the Mnemopi backend is active.
• Subagents do not own separate Mnemopi retain loops; they alias the parent state when a parent Mnemopi state exists, and otherwise remain inert.