Last Updated: 9/2/2026

Troubleshooting and FAQ

Overview

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:

The Local agent CLI row is worth understanding, because it catches a problem the Config row cannot. When your provider is a local agent, the “credential” is a program on your machine rather than a stored key, so a healthy Config row only tells you the provider is selected. This row goes further and actually looks for the binary. If it cannot find one, the message names the sign-in step for that agent, and every commit will otherwise fail quietly. If you set localAgentPath by hand, the message also tells you that discovery was skipped because of it, and how to clear it.

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

jolli doctor --fix

--fix repairs five things:

• Releases a stale worker lock.
• Reinstalls missing git hooks.
• Removes stale dist-path entries.
• Takes a database snapshot when one is overdue.
• Un-parks stuck dashboard events.

One further repair is deliberately held behind a second flag: --fix --forget-dead also drops registry entries whose folder is gone. That deletes those repositories’ memories, and no backup here restores them, so it is never part of a plain --fix.

--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.

The install finished, but there is no jolli command

The symptom is that the install script or npm install -g @jolli.ai/cli runs to the end without an obvious error, and then jolli --version reports that the command does not exist. Almost always this is the Node version.

Jolli Memory requires Node 22.13 or later, and the package refuses to install on anything older. The install script’s own check is coarser than that - it looks at the major version only, so a machine on Node 22.5 through 22.12 passes it, hands off to npm, and npm is the one that refuses. The script does not print npm’s output on a run it considers successful, so the refusal is not shown to you.

Check what you actually have:

node --version

If it is below 22.13, upgrade Node and install again:

nvm install 22.13
npm install -g @jolli.ai/cli
jolli --version

To see the refusal for yourself rather than inferring it, skip the script and run npm install -g @jolli.ai/cli directly - npm prints an EBADENGINE warning naming the version it wanted and the version it found.

You may also see a lower figure quoted while you are setting up. The install script asks for Node 22 or later, because it checks the major version only. 22.13 is the one that is enforced, so a machine on Node 22.5 through 22.12 clears the script’s check and is then refused by npm.

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 fourteen supported sources (see the table above) active in that repo, there is nothing to summarize. Every source except Claude Code, Gemini CLI, and Hermes Agent on macOS and Linux 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:

Your repository uses Husky, lefthook, or pre-commit

This one is worth checking early, because everything looks healthy while nothing is captured. jolli doctor reports Git hooks: installed, jolli status looks normal, and no error appears anywhere - but no commit ever produces a Memory.

Jolli installs its hooks into the repository’s .git/hooks directory. Some hook managers - Husky, lefthook, and pre-commit among them - point git at a directory of their own instead, and git then runs only that directory. Jolli’s hooks are still on disk, which is why the checks pass; git simply never calls them.

Check whether that is what is happening:

git config core.hooksPath

If it prints nothing, this is not your problem. If it prints a path such as .husky, git is reading that directory rather than .git/hooks.

You have two ways forward. If you do not need the other hook manager in this repository, remove the redirect and re-run jolli enable:

git config --unset core.hooksPath
jolli enable

If you want to keep it, call Jolli from the hooks it manages. Add this line to the manager’s post-commit, post-rewrite, prepare-commit-msg, post-merge, and pre-push hooks, passing the matching hook name each time:

[ -x "$HOME/.jolli/jollimemory/run-hook" ] && "$HOME/.jolli/jollimemory/run-hook" post-commit || true

The guard and the trailing || true are deliberate: they keep a missing dispatcher or a Jolli-side error from failing your commit. prepare-commit-msg also needs the arguments git passes it, so forward them with "$@".

Commit again afterwards and run jolli view to confirm a Memory appeared.

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).

Signing in again replaced the key my other machine was using

Signing in from the CLI or an editor creates an API key for you automatically. Because the sign-in has no way to hand you a key you already hold, it replaces the previous one instead: the old key is deleted and a fresh one issued.

Whether that affects another machine depends on the client. Clients that identify the device get a key of their own per device, so two machines do not interfere. Clients that do not send a device name share a single key, and signing in on the second machine invalidates the first.

The fix is the same either way: sign in again on the machine that stopped working. Keys you created yourself under Settings → Jolli Memory are never touched by this, so use one of those if you need a credential that stays put.

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, VS Code Copilot Chat, Cline, Devin, Antigravity, Kimi Code CLI, and Hermes Agent each read a machine-wide file (see the host table in Use Your Memory from Any AI Agent (MCP)). Confirm the file for your host exists and contains the entry.
3. Was the agent installed before you enabled? Registration runs only during an explicit jolli enable; it does not retry on later sessions. If you installed the agent after enabling, run jolli enable again.
4. Restart your host. Your agent reads .mcp.json at startup, so restart it (or reload the window) after enabling.
5. Check that the config file is valid JSON. If the file already exists but cannot be parsed, Jolli leaves it completely alone rather than risk overwriting your other servers, so that one host is skipped while jolli enable still reports success. Nothing appears on screen; the reason is written to .jolli/jollimemory/debug.log in the repo, as a line beginning Skipping MCP registration. Open your host’s config file, fix the syntax (a trailing comma is the usual culprit), and run jolli enable again. An empty file is fine and is treated as a fresh start. Codex is the exception: its config is TOML and Jolli edits only its own block, so a syntax error elsewhere in the file does not stop registration. Codex is skipped only when the file cannot be read at all, such as a permissions problem, logged as Skipping Codex MCP.

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 Use Your Memory from Any AI Agent (MCP).

Turning Jolli Memory off for a repository

Sometimes a repository should not be recorded at all. To turn Memory off for one:

jolli disable

This removes the git hooks and records the choice against the repository, so it stays off. It prints Jolli Memory disabled. Hooks removed. when it worked. Turn it back on with jolli enable, which clears the choice along with reinstalling everything.

Five things are worth knowing before you rely on it:

• It also keeps the repository out of session-statistics uploads, permanently. What the repository recorded before you disabled it is not uploaded later either. Other repositories on the machine keep syncing theirs.
• jolli disable --integrations-only is not a way to turn Memory off. It removes only the repo’s MCP registration and deliberately leaves hooks, skills, and the recorded choice alone. Use plain jolli disable if you want the repository left alone.
• If the choice cannot be written down, nothing is removed. Rather than take the hooks out and risk a later upgrade quietly switching Memory back on, disable stops and tells you, leaving the repository as it was. If you see that, fix the reported problem and run it again.
• The choice is recorded per repository, and it survives. Every worktree of the repository shares it, and automatic setup (including the Claude Code plugin’s, which runs on every session) will not override it. Only jolli enable clears it.
• Jolli’s tools may still appear in your agent afterwards, and that is expected. disable removes the MCP registration that belongs to this repository, which is the entry for Claude Code and Cursor. The other hosts share a single machine-wide entry across every repository you use, so removing it here would break Jolli for all of them; it is left in place deliberately. The tools stay listed, and they simply return nothing for a repository that is turned off.

In IntelliJ the Pause Jolli Memory checkbox in Settings does the same thing, and unpausing re-enables in the same way.

One limitation to be aware of with git submodules: the choice is stored per super-repository rather than per submodule, so turning Memory off inside one submodule turns it off for the other submodules of the same super-repository. Nothing is lost, and you can turn it back on from any of them, but it is wider than it looks.

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, Vercel, Figma, Sentry, 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.
• Statistics about your AI sessions are a separate channel, and it is on when you are signed in. It sends usage figures and tool names, not conversation text, and unlike everything above it covers every repository Jolli is enabled in rather than only the ones you shared. See Does Jolli upload statistics about my AI sessions? below for what it carries and how to turn it off.

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 agents 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 Memory Bank and Sync 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.

Events also carry which AI tool the work happened in, when that is known: one name from a fixed list (claude, codex, gemini, opencode, cursor, cursor-cli, copilot, copilot-chat, cline, cline-cli, devin, antigravity, kimi, hermes) and nothing else - not identity, not content, not a path. When the tool cannot be determined the field is left out rather than guessed, so a missing value means “not measured” and never “the CLI”. Events from clients older than 0.99.14 carry it not at all, and nothing fills it in after the fact.

Telemetry is separate from session statistics, which are not content-free and have their own switch. See the next entry.

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.

Does Jolli upload statistics about my AI sessions?

Yes, when you are signed in. Session statistics are what fill the web dashboard: session counts and durations, models used, token counts, estimated cost, and tool and skill names (including the names of any MCP servers you use). They also carry each session’s title, and many AI tools use your first message as the title. Conversation text, your code, diffs, tool arguments and Memory content are never part of it.

Your memory search queries go up too - the words you type into jolli search - because the dashboard’s Top Search Terms card is built from them. This is free text you wrote, so it is worth knowing about even though the searches themselves are not conversation content.

The scope is wider than anything else here. Everything else in this section leaves your machine only for a repository you chose to share. Session statistics go up for every repository Jolli is enabled in on this machine, connected to a Space or not, whatever the per-repository push switches say: your API key alone says which organization they belong to.

Turning it off, whole machine, persisted:

jolli configure --set syncSessions=false

Or open jolli dashboard and use Settings → Sync to Jolli → Sync session statistics, under the heading Session statistics — for the whole machine, which applies immediately. The editor extensions do not carry this switch, so in VS Code or IntelliJ use the command above.

To leave one repository out, jolli disable there keeps it out for good, including whatever it recorded beforehand. See Turning Jolli Memory off for a repository above.

If nothing is arriving: uploads need you signed in, need Node 22.13 or later (they read the dashboard’s database), and are throttled so several open projects do not each push the same rows. Push what is waiting with jolli doctor --sync-sessions.

Is my content used to train AI models?

No. Jolli’s Privacy Policy  states that your personal information, inputs and data are not used, and not allowed to be used, to train third-party foundational AI models, and says the same specifically of Jolli Memory content.

Generating a summary does send your transcript and diff to the LLM, and nothing about that step retains them - see What is stored where? above for how the request is handled.

Where is my data stored?

In the United States. The Privacy Policy states that all data is stored and processed in the US, and that sub-processors process data in their own US-based infrastructure. Anthropic is named there as an AI service provider.

Remember that most of Jolli Memory never leaves your machine at all: summaries and transcripts live on the git orphan branch and in your Memory Bank folder, and only travel when you Share to a Space or turn on Memory Bank sync. See What is stored where? above.

Is my data encrypted?

Yes, in transit and at rest. Connections use HTTPS/TLS. The Privacy Policy lists AES-256 encryption for stored data, including server-side AES-256 on object storage and AES-256-GCM for API keys, tokens, and any personal information appearing in audit logs.

Where do I find your security and compliance documentation?

For certifications, sub-processor lists, retention commitments from our AI providers, and anything you need for a vendor review, email support@jolli.ai. The Privacy Policy  and Terms of Service  cover data handling.

Related

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