Last Updated: 7/24/2026

Troubleshooting and FAQ

This is the place to look when Jolli Memory is not behaving, and the place to check the common questions before you adopt it.

Part 1 walks through problems in the order they usually happen. Part 2 answers the questions people ask most. Whatever the symptom, run jolli doctor first.

Part 1: Troubleshooting

Start here: jolli doctor

jolli doctor is the first thing to run for any problem. It prints a health checklist and tells you what, if anything, is broken.

jolli doctor

Each line is one check:

If a check fails, doctor exits with an error so you know to act. To repair automatically:

jolli doctor --fix

--fix repairs three things:

• Releases a stale worker lock.
• Reinstalls missing git hooks.
• Removes stale dist-path entries.

--fix does not clear the queue. To remove expired queue data, run jolli clean. To work through a backlog of pending summaries, make one more commit (see Stuck or backlogged queue).

If doctor did not pin the problem, the sections below cover what it does not.

No Memory after a commit

The most common problem. Work through these in order.

1. Restart your agent. This is the single most frequent cause. Two agents capture sessions through hooks, and those hooks only take effect for sessions started after you enabled Jolli. If you enabled Jolli while your agent was already open, restart it (in VS Code or a fork like Cursor or Windsurf, reload the window; in IntelliJ, restart the IDE). Use the table below to see whether your agent needs a restart.

2. Check your credentials. Memory needs a credential to generate summaries. Run jolli status (or check the Status panel). If nothing is configured, set one:

# Sign in with Jolli
jolli auth login
 
# Or bring your own Anthropic key
jolli configure --set apiKey=sk-ant-api03-...

With no credential, doctor reports Config: no credentials, and the log shows No LLM provider available.

3. Confirm hooks are installed. If doctor reports Git hooks: not installed, run jolli enable from the repo root, then commit again.

4. Confirm a supported agent was running. A Memory is built from a conversation transcript. If you committed without one of the twelve supported sources (see the table above) active in that repo, there is nothing to summarize. Every source except Claude Code and Gemini CLI is discovered automatically, so no hook or restart is needed for them, but the agent does need to have produced a session.

5. Check the queue. If everything above is fine, the background worker may be stuck. See the next section.

For deeper diagnosis, open the log. In VS Code, use View -> Output -> Jolli Memory. Common messages:

Stuck or backlogged queue

A stuck lock, or a backlog of queued summaries, usually means the worker crashed or the LLM provider was unreachable for a while.

jolli doctor          # Reports lock state and queue size
jolli doctor --fix    # Releases a stale lock
jolli queue-status    # Reports whether summary generation is still running
jolli clean --dry-run # Previews expired data that can be removed
jolli clean           # Removes expired sessions, queue entries, and squash markers

For a backlog, just make one more commit. The worker picks up where it left off and processes the rest from that point.

jolli clean only removes expired auxiliary data: session entries older than 48 hours, queue entries older than 7 days, and stale squash markers older than 48 hours. Your stored Memories and transcripts are never deleted by clean. In a non-interactive shell (CI, pipes, redirected input) clean refuses to delete unless you pass -y or --yes, so nothing is wiped by accident.

Sign-in failures

If the browser callback page shows an error, match the code below.

If you see “Could not derive Jolli site URL from API key”, your Jolli API key is malformed or incomplete. Regenerate it at Settings -> Jolli Memory -> Create Key and sign in again.

BYOK is always a fallback: if sign-in keeps failing, add an Anthropic key with jolli configure --set apiKey=sk-ant-api03-... and you can still generate Memories (you just cannot use Share in Jolli without a Jolli key).

Share in Jolli failures

Share in Jolli posts a commit’s summary to your Jolli Space. When it fails, the HTTP status tells you why.

To check which workspace you are signed in to:

jolli auth status

If you are not signed in at all, Share asks you to sign in or add a Jolli API key first (in VS Code the button warns “Please configure your Jolli API Key first”; the CLI jolli push reports “Not signed in to Jolli”). Run jolli auth login, or paste a Jolli API key in the Settings panel. A BYOK-only setup (Anthropic key, no Jolli account) cannot use Share in Jolli.

Note: a 429 (rate limit) is not a Share error. It comes from summary generation through the Jolli LLM proxy. Memory retries the summary once within a few seconds; if that retry also fails, it saves a placeholder summary that you can refill later by clicking Regenerate on that commit.

MCP tools not appearing

If your AI agent does not show the Jolli Memory tools (search, recall, and the rest), check these in order.

1. Did enable run? MCP registration happens during jolli enable. Run jolli status to confirm Jolli is enabled in this repo.
2. Is the server registered for your host? .mcp.json in your project root is where jolli enable writes the jollimemory server for Claude Code (and Copilot CLI). Other hosts use their own config: Cursor reads .cursor/mcp.json, and Gemini, Codex, OpenCode, and VS Code Copilot Chat each read a machine-wide file (see the host table in the “Connect Memory to Your AI Assistant (MCP)” doc). Confirm the file for your host exists and contains the entry.
3. Restart your host. Your agent reads .mcp.json at startup, so restart it (or reload the window) after enabling.

If the tools appear but search returns nothing or looks stale, rebuild the local search index:

jolli mcp --reindex

--reindex rebuilds the search index only. It does not register the server or refresh the tool list, so if tools are missing entirely, the fix is in steps 1 to 3 above, not here.

For the full list of tools and how each host connects, see the “Connect Memory to Your AI Assistant (MCP)” doc.

Missing Memory Bank Markdown files

If a visible .md file in your Memory Bank folder was deleted (by you or another tool), restore it:

jolli heal-folder

This re-renders the missing Markdown from the hidden canonical JSON that Jolli keeps alongside it. It does not call the LLM and does not re-summarize anything, so it is fast and free. Your Memories on the orphan branch are the source of truth and stay intact either way.

Healing works only when your storage is in dual-write or folder mode (the default is dual-write). If the repo is set to orphan-only storage, there are no visible Markdown files to heal, and the command tells you so.

Still stuck

File an issue at support@jolli.ai and include your jolli doctor output. That output captures your hook, credential, lock, and queue state, which is exactly what we need to help.

Part 2: FAQ

Will Jolli Memory slow down my commits?

No. Your commit returns immediately. The git hook enqueues the work and hands it to a background worker, then gets out of the way. The summary is generated in a detached process and appears in your editor shortly after, usually within about 10 to 20 seconds. If a summary call fails, it retries once after a short delay, then saves a minimal record so nothing downstream breaks.

Does Jolli Memory send my code anywhere?

Your code stays private by default. Here is exactly what happens:

• Your transcripts stay on your machine by default. They are uploaded only if you turn on syncTranscripts for Memory Bank cloud sync (or run jolli sync-memory-bank --transcripts); they are never sent on Share in Jolli.
• To build a summary, your transcript and git diff are sent to the LLM. Either directly to Anthropic (when you use your own Anthropic key) or through the Jolli LLM proxy (when you signed in with Jolli). The proxy holds the payload in memory only for the request and never stores it or writes it to a log.
• Only the generated summary is saved, and it is saved locally. It leaves your machine when you click Share in Jolli, and then the summary (plus a structured JSON copy), the commit hash, branch, commit author, date, change stats, the changed-file paths, any extracted references (Linear, Jira, GitHub, Notion, Confluence, Asana, monday.com, Slack, Zoom, and Context7 library lookups), your repository’s remote URL, and any attached plans and notes are sent. Raw transcripts and the raw diff are never sent to a Jolli Space.

Does it work offline?

Mostly. Your commit and your local Memory storage work fully offline, because the commit hook and the on-disk storage do not need the network. Only summary generation needs the network, since it calls the LLM. If you commit while offline, the worker records a minimal entry and the summary fills in later. Make one more commit once you are back online and the worker processes the backlog.

Does it work with monorepos and git worktrees?

Yes to both. Jolli Memory is worktree-aware: hooks and summaries work across git worktree checkouts, and each worktree tracks its own current branch so its Memories stay consistent. A monorepo is just one repository, so it works normally. One Memory Bank folder can also hold many repositories, each in its own subfolder.

How do I see what Jolli has captured?

Several ways, depending on where you are:

• In the editor sidebar (Current Branch view). The Committed Memories section lists every commit’s Memory; click the eye icon on one to open it: a Quick recap and per-topic cards with Why this change, Decisions behind the code, and What was implemented callouts, plus Conversations, Context, and Files panels. The Working Memory block above it shows what will go into your next commit’s Memory before you commit, so you can see (and adjust) what is being captured.
• In the Memory Bank. The Memory Bank view browses every stored Memory across branches and repos, with search and a Tree / Timeline toggle. Because the Memory Bank is also plain Markdown on disk (default ~/Documents/jolli/<repo>/), you can open and read it with any tool, no extension required. See Memory Bank and Sync.
• From the CLI.

jolli view                 # compact list of recent memories
jolli view --commit 1      # the latest commit's full Memory
jolli view --commit <hash> # any commit by hash prefix
jolli status               # which assistants and sessions Jolli detected
jolli recall               # the current branch's compiled context

What is stored where?

The orphan branch (jollimemory/summaries/v3) is the source of truth and is completely separate from your code history. See the “Memory Bank and Sync” doc for how the folder is laid out.

Is telemetry on, and can I turn it off?

Usage telemetry is on by default. It is content-free: event names, surface and version, OS and Node version, CPU architecture, a deployment-tier tag, a timestamp, a random install ID, and coarse counts. It never includes your code, file paths, commit messages, diffs, transcripts, Memory content, or repo or branch names. The payload carries no account identifier; note that when you are signed in to Jolli, events upload with your Jolli key, so the server can associate them with your account at ingest. BYOK or signed-out setups upload with no key and stay unattributed.

Turn it off any time with either of these:

# Persisted opt-out
jolli telemetry off
 
# Or the standard environment variable
export DO_NOT_TRACK=1

Check the current state with jolli telemetry status, and see exactly what would be sent with jolli telemetry inspect.

Related

• Getting Started with Jolli Memory - install, sign in, and your first Memory.
• Reference - config keys, commands, and recovery paths.
• Supported AI Assistants and Capture - why a session might not be captured.