oh-my-pi/docs/mnemosyne-memory-backend.md

Mnemosyne memory backend

Oh My Pi can use @oh-my-pi/pi-mnemosyne as a local long-term memory backend.

Set:

memory:
  backend: mnemosyne

Example:

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

With this backend enabled, the coding agent:

1. Opens a local Mnemosyne SQLite database.
2. Recalls relevant memories into a <memories> block before the first model turn.
3. Retains completed conversation turns into the same bank after agent turns.
4. Uses the normal /memory view, /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

Setting	Default	Description
memory.backend	off	Set to mnemosyne to enable this backend.
mnemosyne.dbPath	agent memories dir	Optional SQLite database path.
mnemosyne.bank	project directory name	Base bank name passed to Mnemosyne; the coding-agent wrapper scopes from this base according to mnemosyne.scoping.
mnemosyne.scoping	per-project	Memory visibility mode: global = one shared bank, per-project = isolated project memory, per-project-tagged = project-local writes plus global recall visibility.
mnemosyne.autoRecall	true	Recall memory on the first turn of a session.
mnemosyne.autoRetain	true	Retain completed turns automatically.
mnemosyne.retainEveryNTurns	4	Minimum user turns between automatic retain writes.
mnemosyne.recallLimit	8	Maximum recalled memories in the prompt block.
mnemosyne.recallContextTurns	3	Prior user-bounded turns included in recall queries.
mnemosyne.recallMaxQueryChars	4000	Maximum composed recall query length.
mnemosyne.injectionTokenLimit	5000	Approximate token budget for memory prompt injection.
mnemosyne.debug	false	Enable debug logging for backend failures.
mnemosyne.noEmbeddings	false	Pass noEmbeddings to Mnemosyne and force FTS-only recall.
mnemosyne.embeddingModel	env/default	Embedding model passed to Mnemosyne.
mnemosyne.embeddingApiUrl	env/default	OpenAI-compatible embedding endpoint passed to Mnemosyne.
mnemosyne.embeddingApiKey	env/default	Embedding API key passed to Mnemosyne.
mnemosyne.llmMode	smol	smol uses the configured pi-ai smol model, remote uses the settings below, and none disables LLM calls.
mnemosyne.llmBaseUrl	env/default	OpenAI-compatible LLM endpoint for llmMode: remote.
mnemosyne.llmApiKey	env/default	LLM API key for llmMode: remote.
mnemosyne.llmModel	env/default	LLM model id for llmMode: remote.

Scoping

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

• global uses one shared bank for every project.
• per-project uses a separate bank per project.
• per-project-tagged keeps writes project-local while recall can also read from shared global memory.

The combined project-plus-global behavior lives in the wrapper. The @oh-my-pi/pi-mnemosyne package itself still exposes banks and constructor options directly, including bank for selecting a bank name.

LLM and embeddings

The backend passes these settings to the Mnemosyne constructor; if a setting is omitted, Mnemosyne falls back to its MNEMOSYNE_* environment defaults. The backend does not download or run a local GGUF LLM. LLM-dependent paths use a configured pi-ai model, a dynamic completion function, a remote OpenAI-compatible endpoint, or deterministic no-LLM fallbacks.

FTS-only:

memory:
  backend: mnemosyne
mnemosyne:
  noEmbeddings: true

Equivalent constructor shape:

new Mnemosyne({ noEmbeddings: true });

Remote embeddings:

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

Equivalent constructor shape:

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

Remote LLM:

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

Equivalent constructor shapes:

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

Dynamic function LLM for rotating OAuth tokens:

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

pi-ai smol model LLM:

mnemosyne:
  llmMode: smol

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

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

Operational notes

• The default database lives under the agent memories directory in mnemosyne/mnemosyne.db.
• /memory clear removes the active Mnemosyne SQLite database and sidecar WAL/SHM files.
• /memory enqueue forces retention of the current session and runs Mnemosyne sleep/consolidation.
• Subagents do not auto-retain separate transcript windows; parent sessions own durable retention.