Frequently Asked Questions

Tough questions,
calm answers.

Some of these came from developer DMs; some we anticipated. If yours isn't here, drop us a line — we'll add the answer here.

SECTION A

Architecture & reliability

For the developer who's configured language servers all their life and knows where the bodies are buried.

Q1 Language servers are notorious for memory leaks and crashes. If ArgosBrain embeds LSP, what happens when a server misbehaves? +

Language servers run as separate operating-system processes, never inside the Rust engine's address space. Their lifetime is bound to the ingest run — when the run finishes, the subprocess exits. Two independent timeouts protect against stuck RPC calls and runaway workspace imports. LSP ingestion is opt-in per build, not the default path, and the MCP stdio hot path that serves the agent never spawns a language server — it only reads from the already-ingested graph. A crashed language server cannot affect query latency, correctness, or the zero-panic guarantee.

Q2 What about tsserver / clangd / pylsp on a 10M-line monorepo? Does ingestion scale? +

For languages where a mature SCIP indexer exists (Rust, Python, Go, TypeScript, JavaScript, Java, Scala, PHP, Ruby, C#, Dart), ingestion runs the compiler frontend offline, once, in batch. No long-lived language server. The subprocess dies at the end of ingest, so memory leaks have nowhere to accumulate. LSP live ingestion is used only where no mature SCIP indexer exists yet — Kotlin is the current example. For those, the timeouts above apply.

Q3 What happens if a language-server binary is missing on the user's machine? +

Loud, early failure with a diagnostic message pointing at the missing binary and suggesting install instructions. No silent degradation, no half-indexed state, no retry loop that burns CPU. Ingest either completes cleanly or surfaces an error the user can act on.

Q4 Can your engine panic on malformed input? +

The retrieval path (MCP stdio → graph read → response) is written to the no-unwrap rule: zero unwrap() in library code, every fallible path returns Result. The ingest path is more forgiving (a single malformed file is skipped with a warning), but a panic in ingest still cannot reach the stdio loop — ingest runs on separate tasks and any panic there is caught and logged. The serving path stays up.

SECTION B

Install, integration, and adoption

Because an MCP server that requires editing JSON by hand is dead on arrival.

Q5 Setting up an MCP server means hand-editing claude_desktop_config.json. That's a 50% drop-off at the funnel. What have you done about it? +

Three steps, free, no credit card:

1. Sign in with GitHub at app.argosbrain.com. We auto-issue you a free key — no email, no Stripe.

2. Your dashboard shows a single line you copy. It looks like curl -sSL argosbrain.com/install | sh && argosbrain init --key <your-key>. The key is already filled in.

3. Paste in your terminal. The installer detects your OS + architecture, downloads a checksum-verified binary, installs to ~/.local/bin — no sudo, no package manager, no daemon. argosbrain init then writes the MCP config snippet directly into your client's config file with a backup, so for Claude Code / Cursor / Zed / Continue you never touch JSON.

Honest noteAuto-injection polish is still landing for some clients; current state is documented in INSTALL.md.
Q6 Does it work offline / air-gapped? +

Yes. The retrieval path has no network dependency — it's in-process Rust reading from local bincode storage. Bundle downloads happen at install / sync time; after that, everything is local. An air-gapped setup just pre-stages the bundles.

Q7 Does my code leave my machine? +

No. Your source code, your file paths, your symbol names, your query text, your project names — none of that ever leaves your machine. The brain at ~/.argosbrain/brain.bin is read only by your local binary. Ingestion, storage, retrieval all happen in-process.

We do collect three small things over the network — all on by default, all toggleable in your account settings, all anonymous, none of them code:

  • License heartbeat — paid tiers ping our license server roughly once a day with license id + machine fingerprint hash so we honor cancellations and rotations.
  • Ingest timing telemetry — when first ingest finishes, your binary tells us "chip X + LOC bucket Y took Z seconds" so the next user with chip X gets a more accurate pre-flight estimate.
  • Dashboard counters — once an hour, your binary sends counters (queries served, tokens avoided, $ saved estimate) so your account dashboard shows real numbers in the "this week" panel.

Why on by default: the predictor and dashboard counters are useless on day one if every user has to find a settings page and flip three toggles. We turn them on, document them clearly here and in the privacy policy, and let you turn any of them off without losing functionality. Free tier sends nothing.

Q7a What's the setup wizard? Why does first-run feel different than just "install and go"? +

After you sign in to app.argosbrain.com the dashboard runs a short setup wizard — six steps, takes about five minutes. You see exactly what to do at each step, and the wizard waits until your machine sends back a signal before advancing (so we don't ask "ready?" while your editor is still booting). The steps:

1. Install the binary (one-line curl).
2. cd into your project root — clearly distinct from your home directory or a parent of multiple repos. We refuse to index $HOME directly because that's never what people actually mean.
3. Wire it to your editor (argosbrain init --install-config). Restart the editor.
4. Pre-flight scan — see Q7b.
5. First ingest. We poll your local dashboard until the brain has data, then advance.
6. Done. Optional: install the auto-orchestration hook so blast_radius + reachability run automatically before every Edit your agent does.

If you close the browser mid-wizard and come back tomorrow, polling detects what's already done (license valid, MCP probe responding, brain has nodes) and you resume at the right step. No stored state on our side beyond the license record.

Q7b What does the pre-flight scan tell me before first ingest? +

Five seconds of local measurement gives you an exact prediction instead of "5–10 minutes". The scan looks at:

  • Your repo — file count, LOC, language breakdown (skipping node_modules / target / dist / etc.), largest file, git history depth.
  • Your machine — chip model, RAM, perf cores, whether CoreML (macOS) or CUDA (Linux) acceleration is available, free disk space.

The predictor combines those into a per-stage breakdown: parse + symbols, embedding (the long pole), HNSW index build. Output looks like "~4 min 30 sec on YOUR Mac + YOUR repo · peak RAM ~3.2 GB · brain on disk ~180 MB". If predicted RAM exceeds your free RAM, the scan blocks ingest with concrete options (close apps, use a smaller embed batch, pick a smaller subdirectory). Same blocker fires if you accidentally point it at $HOME or a parent of multiple repos.

The predictor improves over time from the timing telemetry described in Q7. It starts hardcoded from our benchmark runs across eight reference repos and six chips; it gets sharper as more users run it.

Q8 Which agents/IDEs does this work with today? +

Any MCP-compatible client. Confirmed: Claude Code, Cursor, Zed, Continue, Cline (via MCP Agent mode). Aider integrates via its MCP support. Copilot does not support MCP today, so ArgosBrain can't be used inside Copilot — but it happily sits alongside.

Q9 I'm building a custom agent on the Anthropic SDK directly. Can I use ArgosBrain without an MCP-aware client? +

Yes. ArgosBrain runs as a subprocess that speaks MCP; your agent treats each exposed tool as a regular entry in its tools array and forwards the model's tool calls to the subprocess. No framework required, no lock-in to any specific agent runtime.

Honest noteDocumentation for the direct SDK integration is thinner than for Claude Code / Cursor. If you're building this flow and hit friction, tell us — it's the fastest way for us to learn what's missing.
SECTION C

Benchmark and claims

Where we put the numbers and let anyone verify them.

Q10 You built the benchmark you win on. Isn't that a conflict of interest? +

Yes, obviously. That's why LongMemCode is MIT-licensed, publicly hosted, fully deterministic (no LLM judge), and ships with adapter stubs for Mem0 and Zep so anyone can run them and publish results. The whole point of publishing it is to let you disprove us. If someone runs Mem0 through it and publishes a score that beats ours, we update the scoreboard and the pitch. That's the deal.

Q11 Why P99 and not P50? P50 numbers look better for everyone. +

Because agent UX lives at the tail. A memory system with a great P50 and a two-second P99 feels broken every hundred queries. P99 is the honest ceiling for what users actually experience in an interactive IDE loop. We publish P50 too, but we lead with P99 to stay honest.

Q12 Has any competitor actually run LongMemCode? +

Not yet. Adapter stubs for Mem0 and Zep are open in the repo for contribution. Neither has run. Cursor / Copilot / Windsurf memories aren't scriptable enough to run through a benchmark runner, but Mem0 and Zep are — nothing stops them from publishing a score. Their silence is not proof they'd lose; it's just that nobody has done the work yet.

Q13 Your 99.2–100% accuracy sounds too good. What's the catch? +

The catch is that LongMemCode specifically measures structural retrieval quality on code — "does this symbol exist", "enumerate callers of X", "list every override of Y". A well-built code-code verification should be near-perfect on these; they're deterministic questions with deterministic answers. That's the point. If we scored 85% we'd be admitting our engine has bugs. The interesting comparison isn't "100% vs 95%" — it's "100% vs grep-baseline's 6–54%", which tells you what kinds of questions text search literally cannot answer.

Q14 What's the ceiling on this benchmark — could anyone reach 100%, and does that make the scoreboard saturated? +

Yes, the ceiling is 100%, and yes, we think a well-built structural-first system should approach it. The benchmark is designed to be passable by any system that correctly models code as a graph of canonical identifiers — that's the whole argument of the Structural vs Semantic paper. A saturated scoreboard at the structural end is a feature, not a bug: it tells you which paradigms are suited to the workload.

The unsaturated part of the scoreboard is the gap between structural-first systems and everything else. Grep sits at 6–54% depending on corpus; general-memory adapters (Mem0, sbert-faiss) sit below grep on structural ops by design, because the ops are graph questions, not similarity questions. That gap is where the taxonomy lives, and it doesn't close just because someone writes a better embedding.

SECTION D

Operations

What happens in the real loop of ingesting, upgrading, and running the thing day to day.

Q15 How do you handle re-ingest after a git checkout or rebase that touches hundreds of files? +

Re-ingest cost is O(changed files), not O(repo size). Each file carries a content hash; unchanged files are skipped entirely before any parser touches them. On a cold re-run with zero diffs, a large repo completes in under 5 seconds. On a 300-file diff, expect a few seconds on SCIP-backed languages and sub-second on tree-sitter-backed ones. An optional file watcher can pick up changes within half a second of save.

Q16 What's the memory footprint on a big codebase? +

Graph + HNSW stay in a bounded memory budget, with cold tiers spilling to disk and an LRU on hot nodes. The largest corpora we benchmark on LongMemCode (hundreds of thousands of symbols) stay in a few hundred MB resident on a laptop. We publish the numbers per corpus in LongMemCode — they're reproducible.

Q17 What if the bundle format changes in a future version? +

Every bundle header carries a format version. The reader refuses incompatible bundles with a clear error rather than silently misparsing. When the format evolves, the sync path downloads a re-baked bundle automatically. You don't get mysterious failures — you get a message telling you to run one command.

SECTION E

Competitive & strategic

The questions we would rather not have to answer — and exactly because of that, the ones you should read first.

Q18 Cursor / Copilot / Mem0 will copy this in six months. What's your moat? +

Three layers. (1) The benchmark itself: a public, MIT-licensed, deterministic benchmark for code memory didn't exist before LongMemCode. Whoever wants to copy us has to also out-score us publicly, which is a much higher bar than a feature-copy. (2) The ingestion pipeline: running SCIP + live LSP + bespoke tree-sitter drivers with custom semantic hooks in a single engine is not a weekend project. The hook logic per language is where months of work hide. (3) Hot-path cost: the $0/query graph retrieval is an architectural choice that's hard to retrofit onto an LLM-call-per-read product like Letta or a prompt-injection product like Cursor Memories.

Q19 If Anthropic ships a first-party Claude Code memory that does symbol precision, are you dead? +

If they do, they'll do it for Claude Code specifically. ArgosBrain is MCP-native and agent-portable — the same engine serves Claude Code, Cursor, Aider, Zed, Continue simultaneously. The moat narrows on Claude Code, but the cross-agent, cross-IDE story is still ours. Also: first-party memory from any one vendor tends to be scoped to what that vendor's own agent needs. A cross-vendor memory layer has a different customer.

Q20 What happens if MCP itself gets superseded by a different protocol? +

MCP is the transport, not the engine. If the agent ecosystem consolidates on something else, ArgosBrain's graph + HNSW + SCIP/LSP/tree-sitter pipeline ports behind whatever new stdio / gRPC / HTTP interface wins. The expensive part — the ingestion and the graph — doesn't move.

Q21 You're local-first. Enterprise customers want cloud / SSO / audit logs. What's your answer today? +
Honest noteWe don't have it shipped. Multi-user sync is on the roadmap, not in production. For now, an enterprise buyer who needs cloud-managed multi-user memory should use Mem0 Cloud or Zep for conversational agents, or contact us for an Enterprise rollout that includes the missing pieces. We'd rather have this conversation honestly than pretend we're further along than we are.
Q22 "MCP is dead" — someone wrote it burns tokens, is unreliable, and is a security hole. Where does that leave you? +

That argument is aimed at MCP servers that proxy whole third-party products — Figma, Notion, Linear — and expose a hundred tool descriptors the model has to re-read on every turn. At that scale, yes: context gets eaten, the model misuses tools it doesn't fully understand, and a prompt injection can reach real external side-effects.

ArgosBrain is a different shape.

  • Descriptor cost is bounded. We expose 31 tools with strict JSON Schemas, ~5k tokens of descriptor weight at session start. Any session that issues three or more retrievals amortises that cost, because each retrieval returns hundreds of bytes instead of the thousands of tokens a Grep loop would have cost.
  • No runtime ambiguity. Every retrieval tool is deterministic for exact-match queries (symbol_exists, resolve_member, callers, etc.) and reports confidence grades (CLEAR / AMBIGUOUS / NoConfidentMatch) on semantic queries. Returns are typically sub-millisecond on warm-cache, and produce small, typed outputs. The model isn't "figuring out rules at runtime" — the rules are the schema.
  • No external blast radius. Every tool is read-only over a local graph of the user's own code. A prompt injection that says "dump the database" hits a tool surface that literally has no database to dump. The worst a malicious prompt can do is look up a symbol that is already on disk on the machine it ran on.

The critique is valid for "MCP as a universal proxy layer." It isn't valid for "MCP as a transport for a deterministic, local, read-only retrieval engine." That's the shape we picked, on purpose.

SECTION F

About the product

Two small questions about the tool itself.

Q23 Why Rust? +

Because sub-millisecond P99 at laptop RAM means you can't afford a GC pause or an interpreter overhead, and because the MCP process is going to run next to an agent that already eats RAM. Rust gives us predictable latency and a tiny footprint without giving up crash safety. Plus, the tree-sitter and async-lsp ecosystems are already first-class Rust citizens.

Q24 You call it "ArgosBrain" publicly and "Neurogenesis" in docs. Why two names? +

Product vs architecture. "ArgosBrain" is what users install and type into a config file. "Neurogenesis" is the internal codename for the graph engine and shows up in crate names, research references, and architecture docs. It's the same thing; one is the noun, the other is the proper name.

Q25 What does "branch-aware" actually mean? Can I really compare a feature branch with main in one session? +

Yes. ArgosBrain holds two live brains in one MCP session — the branch you're working on and the main-branch baseline — and every retrieval tool (search, recall, callers, resolve_member) returns both sides side-by-side. So when you call callers("BrainGraph::add_node") on a refactor branch, the response shows you the 12 callers on your branch and the 14 on main, with the diff highlighted. Use case: refactoring with a structural safety net, PR review without leaving the agent. Shipped in v0.13. Nobody else in this category has it.

Q26 What's the Argos Companion hook? Does it slow my agent down? +

It's a Claude Code PreToolUse hook (~$HOME/.claude/hooks/argos-companion.sh) that fires before every Grep / Read / Glob tool call and injects a non-blocking system reminder pointing the agent at the matching mcp__argos__* tool. It does not block the call — your Grep still runs. The point is complementary: agents read CLAUDE.md once at session start and the "Argos-first" rule fades from attention, so the hook re-surfaces it at the exact moment the agent is about to use Grep alone for what's structurally a symbol query. Latency: under 5 ms per fire. Install: copy the script to ~/.claude/hooks/ and add a one-line PreToolUse entry to ~/.claude/settings.json. Source + install docs: docs/ARGOS_COMPANION_HOOK.md.

Q27 What do I lose on Free vs Pro? Be specific. +

One thing: multi_project. On Free you bind ArgosBrain to one repo at a time via argosbrain init. Switch repos with argosbrain abandon-primary (releases the slot, optionally deletes the old brain.bin). Everything else — full retrieval (search / recall / symbol_exists / resolve_member / callers / etc.), the complete sinks library at all three levels, reachability + blast-radius analysis, dead-code detection, API and architecture diffs, trends, all 32 ArgosBrain skills — is on Free. Pro at $19/month removes the one-project lock so you can keep N repos warm in the same Manager. Free is non-commercial use only (commercial = paid client work, billable hours, integration into for-profit products) per the Terms §07.

Q28 I'm on Free and want to switch to a different repo. How? +

Run argosbrain abandon-primary in your terminal. The command reads the marker at ~/.argosbrain/free-primary.txt, asks if you want to delete the old project's brain.bin (your call — default is keep), and clears the marker. Your next argosbrain init in any other directory becomes the new active project. No limit on how many times you can swap. The brain files of inactive projects stay on disk and reactivate the moment you point a fresh init at them — so a Free user with three projects rotated weekly never loses graph state, just access at a given moment.

Still have questions?

Drop us a line — we'll add the answer here.