Troubleshooting

Troubleshooting

Start with doctor

logos doctor                  # vault, hosts, continuity, privacy, index, review queue
logos doctor --verbose        # plus model runtimes and tiers
logos doctor --integration    # prove each host can reach this vault, with a real round trip
logos doctor --probe          # which local models load and follow JSON schemas
logos doctor --egress         # every address logos can contact
logos doctor --report         # a bundle you can paste into a bug report

Each failing check prints a → line with the command that fixes it.

My agent doesn't seem to remember anything

1. Is it pointed at the right vault? Run logos doctor --integration. A host with a relative or wrong LOGOS_VAULT completes the handshake but sees an empty vault. Re-run logos setup (or logos mcp install --host <name>) to re-pin it with absolute paths.
2. Did the last session checkpoint? logos show and logos show --history show the last checkpoint. If there's none, the agent never called checkpoint. In hosts without the plugin, ask for it ("checkpoint before you stop"), or use /handoff in Claude Code.
3. Was it filtered out by time? resume narrows to a window based on the gap since your last checkpoint, and says what it set aside. Ask for since: all.
4. In Cursor or Codex, did the session-start hook run? Codex needs it approved in /hooks. Otherwise those hosts restore context only when the model calls resume.

The agent never mentions Logos

Hosts collapse tool results. Expand them (Ctrl+O in Claude Code) to see the receipts. If the agent isn't calling the tools at all, add the instructions from The Handoff Loop to its system prompt or AGENTS.md.

Search misses things worded differently

Without an embedding model, search and before_you_try match by wording only, and say so in their output. Install Ollama and run logos setup (or ollama pull nomic-embed-text), then logos index.

The index looks wrong or stale

logos index                          # re-sync
rm -rf "$LOGOS_VAULT/.logos" && logos index   # rebuild from scratch; nothing is lost

"vault not found"

LOGOS_VAULT points at a folder that doesn't exist. Run logos setup to create one, or point the variable at your existing vault.

The privacy check fails

The vault is readable by other accounts on this machine. Doctor prints the chmod -R go-rwx <vault> that fixes it.

A project has two names

This happens when a folder is renamed or reached by a different path. logos project-name shows what the current directory resolves to. logos project rename <old> <new> --merge folds one into the other, history included.

Moving from brain (0.4)

Logos was developed as brain. Since 0.5.0 the old names (brain, BRAIN_*, .brain/) aren't read, and Logos warns on stderr, naming the fix, whenever it finds one.

logos migrate --dry-run     # the plan
logos migrate --yes         # move ~/brain to ~/logos, leave a link, re-pin hosts
logos doctor

• Restart open agent sessions afterwards, since they still hold the old path.
• If Claude Code ends up with the vault registered twice, run logos mcp install --host claude-code --yes.
• To keep the old settings: inside the vault, mkdir -p .logos && cp -n .brain/*.json .logos/, then delete .brain/. Don't mv .brain .logos.
• A host wired by 0.4.0–0.4.2 pins BRAIN_VAULT. Doctor names it, and logos setup --vault <path> re-pins it.

Reporting a bug

logos doctor --report

Paste the output into a GitHub issue. It contains paths and versions, not vault content.