librechat-mnemonic

Automatic, project-scoped long-term memory for LibreChat, backed by a local mnemonic MCP server.

Chats inside a LibreChat project recall that project's memories and write new ones back to it. Chats outside a project use the global pool. It is on by default and can be turned off per chat, per user, or entirely.

Nothing is forked or patched. This runs as one container alongside LibreChat.

What it does

• Recalls before every turn. Relevant memories are retrieved and injected as context before the model is called. This does not depend on the model deciding to call a tool.

• Writes after every turn. Durable facts are extracted from the exchange and stored, with duplicates detected and skipped.

• Tells the model what time it is. Every user-facing turn carries the current UTC timestamp and unix time, so "today", "next week", and "is this memory still current?" are answered against the clock instead of the training cutoff.

• Scopes by LibreChat project. A chat in the "Home Network" project reads and writes memories stamped with that project. Memories live in one global vault, partitioned by project, so nothing is siloed unless you want it to be.

• Stays out of the way. /memory off in any chat, and that conversation stops recalling and storing.

• Caches aggressively. Note bodies, recall results, and memory settings are cached with configurable TTLs to keep latency low. Cache stats are exposed via /healthz and Langfuse span metadata.

• Traces and monitors usage for every turn that calls a model. When Langfuse credentials are set, every chat-completions/messages turn that reaches the upstream provider is traced — memory on or off, with or without a conversation id — with an upstream generation carrying model and token usage, plus spans for resolve-context, recall, and memory-write when memory is enabled. /memory commands are answered locally and never call a model, so they produce no trace.

• Exposes tools too. An MCP endpoint lets agents search, correct, and forget memories explicitly when the automatic path is not enough.

Related MCP server: Memory Crystal MCP Server

How it works

browser  →  LibreChat  →  librechat-mnemonic  →  your model provider
                 │               │
                 │               ├── stdio ──→  mnemonic  ──→  vault (markdown + git)
                 │               │
                 └──── mongo ────┘   (read-only: conversation → project)

LibreChat has no server-side plugin API, so the integration hangs off two supported extension points:

1. Custom endpoints with header placeholders. LibreChat resolves {{LIBRECHAT_USER_ID}} and {{LIBRECHAT_BODY_CONVERSATIONID}} into request headers. That is how the proxy knows who is asking and in which conversation.

2. MCP servers over streamable HTTP, for the explicit tool surface.

The project is not in the request. LibreChat's ALLOWED_BODY_FIELDS is conversationId, parentMessageId, messageId and nothing else, so the proxy resolves it itself: conversations.chatProjectId → chatprojects.name, read from the same MongoDB LibreChat already uses. Its own collections are never written to.

Why a proxy and not just MCP tools

Because "automatic" and "the model decides" are different things.

LibreChat's own memory feature can be driven externally: with memory.agent.enabled unset, every run loads memories from the MemoryEntry collection and injects them with no tool call involved. But that lookup is keyed by user id alone. There is no conversation or project dimension in the schema, and the load happens inside LibreChat before anything external runs. So that channel gives automatic but user-global.

The only place that can see the project is the request path. Hence a proxy.

The MCP tools are still worth having, they just do a different job: correcting a memory the extractor got wrong, or searching for something the recall query missed.

Requirements

• LibreChat v0.8.7 or later (projects landed in 0.8.7; header placeholders are older)

• Access to LibreChat's MongoDB

• An embedding provider for mnemonic: a local Ollama, or an OpenAI or Gemini key

Quick start

Add the service to your LibreChat compose file. See docker-compose.example.yml for the annotated version.

services:
  librechat-mnemonic:
    image: ghcr.io/claudedowling/librechat-mnemonic:latest
    restart: unless-stopped
    environment:
      LIBRECHAT_MONGO_URI: mongodb://mongo:27017/LibreChat
      UPSTREAMS: >-
        [{"name":"openai","baseUrl":"https://api.openai.com","api":"openai"}]
      OLLAMA_URL: http://ollama:11434
    volumes:
      - mnemonic-vault:/vault
      - mnemonic-projects:/projects
    networks: [librechat-network]

Then point LibreChat at it in librechat.yaml:

endpoints:
  custom:
    - name: 'OpenAI'
      apiKey: '${OPENAI_API_KEY}'
      baseURL: 'http://librechat-mnemonic:8710/openai/v1'
      models:
        default: ['gpt-4o']
      headers:
        x-librechat-user-id: '{{LIBRECHAT_USER_ID}}'
        x-librechat-conversation-id: '{{LIBRECHAT_BODY_CONVERSATIONID}}'

Restart LibreChat. Send a message. Type /memory status to confirm it is wired up.

The full example, including Anthropic and the MCP server, is in examples/librechat.yaml.

In-chat commands

The proxy answers these itself. The model is never called and no tokens are spent.

Precedence is per-chat, then per-user, then MEMORY_DEFAULT_ENABLED.

Current date and time

Models have no clock. Left to itself a model dates "today" from its training cutoff, which makes every relative reference wrong and makes it impossible to judge whether a recalled memory is a week or a year old.

So each user-facing turn gets a small system block ahead of the memory block:

<!-- librechat-mnemonic:datetime -->
# Current date and time

This turn started at:

- UTC: 2026-08-30T04:05:06Z (Sunday, 30 August 2026)
- Unix time: 1787040306 (seconds since 1970-01-01T00:00:00Z)

Both representations are there on purpose: ISO-8601 for the model to read and quote, unix seconds for arithmetic that does not require parsing a calendar. It is always UTC — the proxy has no way to know the user's timezone, and a wrong one is worse than an explicit one.

This is independent of memory. It still happens in a chat with /memory off. It does not happen on LibreChat's side calls (title generation, its own memory agent), which have no conversation id and are forwarded exactly as sent. Set PROMPT_DATETIME_ENABLED=false to turn it off.

How project scoping works

mnemonic derives project identity from a working directory. Its detection order is the git remote of the enclosing repo, then the git root folder name, then the plain basename of the directory. This uses the third branch: each LibreChat project gets a directory under MNEMONIC_PROJECT_ROOT, and its name becomes the mnemonic project.

A LibreChat project called Home Network becomes /projects/Home Network, which mnemonic resolves to { id: "home-network", name: "Home Network", source: "folder" }.

Writes use scope: global with that directory as cwd. mnemonic stores the note in the main vault while stamping it with the detected project. The note's frontmatter carries project: home-network and projectName: Home Network. That is what "one global vault, partitioned by project" means in practice.

What each recall scope actually returns

Verified against mnemonic 0.42, because the tool descriptions are misleading on this point:

Note that global does not mean "notes with no project". mnemonic's tool description still says it returns only unscoped memories; the implementation returns every note in the main vault regardless of project stamp. If you need memories from one project kept out of another, use project.

Three more things to know:

• The project directory must exist, and must exist on the filesystem of whichever process runs mnemonic. mnemonic calls simpleGit(cwd) outside its error guard, so a missing path fails the whole call. In the default spawn mode this is handled for you. With MNEMONIC_MODE=remote it is your job.

• MNEMONIC_PROJECT_ROOT must not be inside a git repository. If it is, mnemonic will attribute every memory to that repo instead of to the project.

• Project names collide. Two LibreChat users with a project of the same name share one mnemonic project. This service is designed for single-user and small-trusted-team installs; see Limitations.

Configuration

Everything is environment driven. Only LIBRECHAT_MONGO_URI and UPSTREAMS have no useful default.

LibreChat

Upstreams

UPSTREAMS is a JSON array. Each entry mounts a provider at /<name>/..., and everything after the name is forwarded verbatim.

mnemonic

mnemonic's own variables (EMBED_PROVIDER, OLLAMA_URL, EMBED_MODEL, OPENAI_API_KEY, GEMINI_API_KEY, DISABLE_GIT, …) are passed through to the spawned process. See mnemonic's configuration.

Behaviour

Extraction model

Leave unset to reuse the chat's own model and credentials. Setting a small dedicated model is cheaper.

Caching

Three independent caches keep latency low. All TTLs are configurable so you can trade freshness for speed. Cache hit/miss stats are reported on the /healthz endpoint and in Langfuse span metadata.

Telemetry

When Langfuse credentials are set, the proxy creates its own Langfuse tracer and traces every chat-completions/messages turn that calls a model, whether or not memory is enabled and whether or not LibreChat sent a conversation id (side calls such as title generation are traced too). /memory commands are handled locally and never reach the model, so they produce no trace. Traces use sessionId = conversationId when one is present, so they correlate with LibreChat's own Langfuse traces. The upstream observation is a generation carrying the model name and token usage (prompt/completion/total), extracted from the upstream response for both OpenAI and Anthropic wire formats, streaming or not. resolve-context, recall, and memory-write spans are only added when memory is enabled for that turn.

Telemetry uses the Langfuse v5 SDK (@langfuse/tracing + @langfuse/otel), the same OpenTelemetry-based stack LibreChat uses. A trace is an OTel span, so chat-turn and mcp-tool traces carry real start and end times and render identically to LibreChat's. The OTel tracer provider is isolated to Langfuse's own tracer — it is never registered globally, so nothing else in the process is instrumented.

MCP tool calls are traced as mcp-tool, with the tool arguments recorded as the trace and span input and the tool's reply text as the output, so a trace shows what was searched for and what came back rather than just the tool name. Each tool span is broken down into child spans (see Langfuse below) so a slow call shows where the time went.

Share the same LANGFUSE_* credentials with LibreChat's own config (e.g. via Docker Compose env vars from 1Password or your secret manager) so traces from both services appear under the same session.

When either key is missing, telemetry is a no-op with zero overhead.

Service

Tiered models and failover

Optional, and no code in this service is involved. If you want basic / standard / advanced to behave as models that fall back to another provider when the first one runs out of credit, put LiteLLM behind this proxy:

LibreChat  ->  librechat-mnemonic  ->  LiteLLM  ->  Ollama / OpenAI / Gemini

LiteLLM speaks OpenAI format on /v1/chat/completions, so it is an ordinary UPSTREAMS entry. See examples/litellm-config.yaml, the optional services in docker-compose.example.yml, and the Mnemonic endpoint in examples/librechat.yaml.

The order matters. mnemonic in front means memory recall and injection happen exactly once per turn and LiteLLM is just an upstream that happens to be several providers. LiteLLM in front would need one mnemonic route per provider, and every failover attempt would re-enter memory injection.

Because LibreChat agents bind to {endpoint, model}, failover at the model layer is invisible to the agent. Point an agent at advanced once and you never edit it again when a provider runs dry.

Things that bite, in rough order of how much:

• Every model in a group must support tool calling. Agents send tools on every request. A target without function calling does not degrade the reply, it breaks the agent, and nothing warns you.

• Pin EXTRACT_BASE_URL / EXTRACT_MODEL / EXTRACT_API_KEY. Left unset, extraction reuses the chat's own upstream and model, which under a tier resolves to LiteLLM with the tier name as the model — memory extraction then inherits your failover chain and can run on the expensive fallback.

• Failover only works before the first byte. Auth, quota, rate-limit and connection failures arrive in the response status, so the common cases are covered. A provider that dies mid-stream loses the turn; nothing downstream can recover it.

• Credentials live in LiteLLM. LibreChat sends one API key per endpoint, but a tier spans providers, so the inbound credential is meaningless. apiKey: 'not-needed' in librechat.yaml is a placeholder; the proxy replaces it with the apiKey from its UPSTREAMS entry, which should be a scoped LiteLLM virtual key, never the master key.

• LiteLLM budgets track its own spend, not your remaining provider quota. They cannot see an OpenAI credit balance or a subscription allowance. Their real value is the other direction: a cap on the paid target, so a stopped Ollama cannot silently drain it.

• /healthz knows nothing about tiers. Circuit state lives in LiteLLM's own /health, and traces land as two sibling generations in Langfuse rather than nested — they correlate by session id.

• The admin UI needs Postgres. Without a database LiteLLM is config-file only, with no UI and no budgets. Logging in as admin with LITELLM_MASTER_KEY is the default; setting UI_USERNAME / UI_PASSWORD costs nothing and keeps the root credential out of a browser form.

Monitoring

/healthz

Returns JSON with service status, upstream names, telemetry status, cache stats for all three caches, and mnemonic call counters:

{
  "ok": true,
  "upstreams": ["openai", "anthropic"],
  "telemetry": "on",
  "cache": {
    "noteBody": { "hits": 42, "misses": 3, "size": 12, "hitRate": 0.93 },
    "recall": { "hits": 8, "misses": 15, "size": 5, "hitRate": 0.35 },
    "settings": { "hits": 120, "misses": 6, "size": 9, "hitRate": 0.95 }
  },
  "mnemonic": {
    "connected": true,
    "connects": 1,
    "transportErrors": 0,
    "circuitOpenMs": 0,
    "inFlight": { "read": 0, "write": 1 },
    "timeoutMs": 20000,
    "slowCallMs": 5000,
    "tools": {
      "recall": {
        "calls": 214,
        "errors": 3,
        "timeouts": 3,
        "totalMs": 96400,
        "maxMs": 20001,
        "maxQueueWaitMs": 8600
      }
    }
  }
}

connects above 1 means the connection has been re-established — a spawned mnemonic that crashed, or a dropped HTTP session. maxQueueWaitMs approaching timeoutMs means the calls are queueing, not the vault being slow.

Debugging mnemonic timeouts

Every mnemonic call is logged with a phase breakdown, so a timeout is attributable without Langfuse:

{
  "level": 50,
  "callId": 417,
  "tool": "recall",
  "queue": "read",
  "queueDepth": 2,
  "queueWaitMs": 11840,
  "connectMs": 0,
  "callMs": 20001,
  "totalMs": 31841,
  "outcome": "timeout",
  "phase": "mnemonic",
  "inFlight": { "read": 2, "write": 1 },
  "recentStderr": ["..."],
  "msg": "mnemonic call timed out"
}

Levels are chosen so the useful lines survive LOG_LEVEL=info:

Set LOG_LEVEL=debug for the per-call lines, or MNEMONIC_STATS_INTERVAL_MS=60000 for a once-a-minute summary at info without the volume. That summary carries two views:

• window — counters for the interval just elapsed, reset each time it prints. This is the one to watch: a bad minute has its own calls/timeouts/maxMs, rather than nudging a lifetime average.

• lifetime — the same cumulative totals /healthz serves, kept alongside as the baseline to compare the window against.

Reading the result:

• phase: "queue" with a high queueDepth — calls are backing up in this service, not in mnemonic. Reads and writes have separate queues but each is serialised, so a burst of concurrent chats queues behind itself. Check whether post-turn writes (each one a dedupe recall plus a remember) are overlapping the next turn's recall.

• phase: "mnemonic" — the vault is slow. Usually embedding: a remote EMBED_PROVIDER or a cold Ollama model. Compare searchMs against hydrateMs in recall complete to see whether it is the search or the note fetch.

• phase: "connect", or connects climbing on /healthz — the transport keeps dropping. In spawn mode check recentStderr for the child process dying; in remote mode check the HTTP session.

Langfuse

When enabled, each chat turn that calls a model produces a trace with three spans and one generation:

The trace itself is the root chat-turn span, ended as soon as the response is sent. memory-write outlives it and is exported on its own end, so a detached write never holds the trace open.

MCP tool calls produce an mcp-tool trace whose tool span is broken down into child spans, so a slow call is attributable rather than just slow:

mcp-tool                      mcp-tool
└─ search_memory              └─ save_memory
   ├─ queue_wait                 ├─ queue_wait
   ├─ connect                    ├─ connect
   ├─ mnemonic.recall            ├─ mnemonic.dedupe
   └─ mnemonic.get               └─ mnemonic.remember

Spans carry mnemonic.tool, mnemonic.timeout_ms, mnemonic.cache_hit, and mnemonic.result_count as metadata — mnemonic.tool is what tells the two queue_wait spans apart. When a mnemonic call fails, the proxy still degrades gracefully (empty recall, saved: false), but the span carries the exception with level: ERROR so the failure is visible in Langfuse and not only in the server logs.

Filter by sessionId in Langfuse to see all turns for a conversation.

MCP tools

Available at /mcp for LibreChat agents.

The server ships serverInstructions telling the agent that recall is already automatic, so it should reach for these only when the automatic path falls short.

Limitations

Worth knowing before you rely on it.

• The first turn of a brand new chat may miss its project. The conversation document may not be written when the first request arrives. The proxy retries once, and the post-turn write re-resolves the project, so writes are correct from turn one. The very first recall can fall back to global.

• Only traffic routed through the proxy is augmented. Endpoints configured to talk to a provider directly get no memory. That is deliberate: the proxy cannot see what it does not carry.

• Project names are the identity. Renaming a LibreChat project starts a new mnemonic project; the old memories stay under the old name. Directories under MNEMONIC_PROJECT_ROOT can be renamed to match, but nothing does it for you.

• Multi-user installs share memory by project name. There is no per-user partition in the vault. Fine for a personal or small-team instance, wrong for a multi-tenant one.

• Automatic extraction is a judgement call made by a model. It will sometimes store something you would not have, and miss something you would. MEMORY_WRITE_MODE=explicit trades recall for precision.

• Tool-calling turns are passed through untouched. Memory is injected on the request and extracted from the final text, so intermediate tool rounds are not analysed separately.

• Nothing can fail over mid-stream. Once an upstream has responded and the status and headers are relayed, the proxy is committed: a provider that dies after the first byte loses the turn. This is true of any failover layer behind the proxy, including LiteLLM.

• Cache TTLs trade freshness for latency. If you change a memory via the MCP tools or another mnemonic client, the proxy may serve stale cached results for up to the TTL. The defaults are conservative; lower them if you need faster consistency.

Images and releases

Published to the GitHub Container Registry:

ghcr.io/claudedowling/librechat-mnemonic:latest    # newest release
ghcr.io/claudedowling/librechat-mnemonic:0.1       # newest 0.1.x
ghcr.io/claudedowling/librechat-mnemonic:0.1.0     # exact version
ghcr.io/claudedowling/librechat-mnemonic:main      # tip of main, unreleased

Built for linux/amd64 and linux/arm64, with SBOM and signed build provenance. Verify a pull with:

gh attestation verify oci://ghcr.io/claudedowling/librechat-mnemonic:latest \
  --repo claudedowling/librechat-mnemonic

Pin to a minor tag such as :0.1 in production. latest moves across breaking changes while the project is pre-1.0.

To cut a release, bump version in package.json, then tag:

git tag v0.1.0 && git push origin v0.1.0

Development

npm install
npm test          # unit tests
npm run typecheck
npm run dev       # watch mode

Requires Node 22 or later.

The pieces worth understanding first: src/memory/service.ts holds the scoping rules that both entrypoints share, src/proxy/handler.ts is the request path, and src/mnemonic/projects.ts explains the directory trick and the constraints that come with it.

Licence

MIT