Troubleshooting AtomicMemory: Common Issues and Fixes

Most AtomicMemory setup issues fall into a small number of categories: the Core service is not reachable, authentication credentials don’t match, the SDK was not initialized in the right order, or a scope field is missing from a memory call. The items below cover every common failure mode with concrete diagnostic commands and fixes. If you work through these and the issue persists, run atomicmemory doctor — it checks service connectivity, configuration, and hook installation in one pass.

Connection refused on port 17350

The Core service is not reachable at http://localhost:17350. This is almost always one of three things: the Docker container is not running, the container was started without binding the port to your host, or a firewall is blocking the connection.Step 1 — Check that the container is running:

docker ps | grep atomicmemory

If the container is not in the list, start it:

docker run --rm -it --pull always \
  -p 127.0.0.1:17350:17350 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $HOME/.atomicstrata/atomicmemory-docker:/var/lib/atomicmemory/postgres \
  ghcr.io/atomicstrata/atomicmemory-core:latest

Step 2 — Check the port binding:The container must be started with -p 127.0.0.1:17350:17350. If you started the container without -p, the port is not bound to your host even though the container is running. Stop the container and restart it with the flag.Step 3 — Verify the service responds:

curl -s http://127.0.0.1:17350/health

A healthy response looks like {"status":"ok"}. If the command hangs, check your firewall rules. If it returns a connection error, the container is not running or not bound to that address.

Authentication errors (401 Unauthorized)

A 401 Unauthorized response means the bearer token in your request does not match the CORE_API_KEY value configured on the Core service.For local development, the default key is local-dev-key. Set it explicitly in your request header:

curl -s http://127.0.0.1:17350/health \
  -H "Authorization: Bearer local-dev-key"

Check what key the SDK is using:If you are using the TypeScript SDK, verify the apiKey value in your MemoryClient configuration matches the key the Core container was started with:

const memory = new MemoryClient({
  providers: {
    atomicmemory: {
      apiUrl: 'http://localhost:17350',
      apiKey: 'local-dev-key', // must match CORE_API_KEY
    },
  },
});

Check service status from the CLI:

atomicmemory status

This command verifies connectivity and authentication in one step and reports which key is in use.For production deployments, generate a strong random key and set it consistently:

export CORE_API_KEY=$(openssl rand -hex 32)

Pass the same value both to the Docker container (-e CORE_API_KEY=$CORE_API_KEY) and to your application configuration.

SDK initialization fails

If you see errors like MemoryClient is not initialized or calls to memory.memory.* or memory.storage.* throw unexpectedly, the most common cause is calling SDK methods before await memory.initialize() has completed.Always await initialize() before making any calls:

import { MemoryClient } from '@atomicmemory/sdk';

const memory = new MemoryClient({
  providers: {
    atomicmemory: { apiUrl: 'http://localhost:17350' },
  },
});

// This must complete before any memory.* or storage.* calls
await memory.initialize();

// Now safe to use
await memory.ingest({ ... });

Check your Node.js version:The @atomicmemory/sdk package requires Node.js 22 or later. Check your version:

node --version

If you are on an older version, upgrade to Node.js 22 LTS or Node.js 24.

Scope errors: 'at least one scope field required'

AtomicMemory requires every memory operation to be scoped. If you see an error like "at least one scope field required" or a 400 response mentioning scope, you are missing a scope object in your call.Add a scope to every ingest and search call:

// Ingest with scope
await memory.ingest({
  mode: 'messages',
  messages: [{ role: 'user', content: 'I prefer aisle seats.' }],
  scope: { user: 'your-user-id' },  // required
});

// Search with scope
const results = await memory.search({
  query: 'seat preference',
  scope: { user: 'your-user-id' },  // required
});

The scope object accepts any combination of user, agent, namespace, and thread. At least one field must be present. The SDK will reject scopeless requests before they reach the network to prevent you from accidentally writing or searching across all users.

No tools appear in Cursor or Codex

If AtomicMemory tools are not showing up in Cursor or Codex after configuring the MCP server, work through these checks in order.Step 1 — Restart the editor:Both Cursor and Codex read MCP configuration at startup. If you changed the MCP config file while the editor was running, the new tools will not appear until you restart.Step 2 — Verify the MCP server runs:Open a terminal and run the MCP server directly to confirm it starts without error:

npx -y @atomicmemory/mcp-server

If this exits with an error, fix the error before restarting the editor.Step 3 — Check the scope user variable:The MCP server requires ATOMICMEMORY_SCOPE_USER to be set so it knows which user scope to attach to memory operations. Verify it is in your shell environment or in your MCP config:

echo $ATOMICMEMORY_SCOPE_USER

If it is empty, add it to your shell profile or to the env block of your MCP configuration file.

MCP server errors in Claude Code

If the AtomicMemory MCP server is producing errors inside a Claude Code session, use the built-in diagnostic tools to identify the root cause before making changes.Run the diagnostic check:

atomicmemory doctor

This checks Core connectivity, authentication, MCP server availability, and hook installation in one pass and reports actionable findings.Verify Core is running:

atomicmemory status

The MCP server cannot function if the Core service is not reachable.Reinstall the lifecycle hooks:If the diagnostic reports missing hooks, reinstall them:

atomicmemory hooks install --host claude-code --runtime node

The Claude Code plugin installs both the MCP server configuration and lifecycle hooks. The hooks capture context at session start, on each user prompt, and before and after context compaction. If the hooks are missing, memory capture will not occur automatically.

Embeddings are slow

Slow embedding performance on the first run is expected when using the transformers embedding provider. This provider runs locally using WASM/ONNX inference and must download the embedding model on first use.Wait for the model download to complete:After the first run, the model is cached locally and subsequent calls are significantly faster. The download only happens once per model version.Switch to the OpenAI embedding provider for faster embeddings:If you have an OpenAI API key, switching to the openai provider eliminates the local inference overhead:

# In your .env or container environment
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
EMBEDDING_DIMENSIONS=1536

Restart the Core container after changing the provider. Note that changing the embedding provider after you have already ingested memories will require re-ingesting your data, because the new embeddings will be dimensionally incompatible with the existing ones.

The transformers provider is the right choice for fully local, offline, or privacy-sensitive deployments where you do not want embeddings leaving your machine. For production workloads where latency matters, openai or openai-compatible providers are recommended.

Ingest runs but no memories appear

If your ingest calls return success responses but search returns no results, the most common cause is a scope mismatch between the ingest call and the search call.Check that ingest and search scopes match:The scope you provide on ingest must match or overlap with the scope you use on search. If you ingested with scope: { user: 'alice' } but searched with scope: { user: 'bob' }, you will get no results.

// Ingest
await memory.ingest({
  mode: 'messages',
  messages: [{ role: 'user', content: 'I work in London.' }],
  scope: { user: 'alice' },
});

// Search — scope must match
const results = await memory.search({
  query: 'where does alice work',
  scope: { user: 'alice' },  // same scope as ingest
});

Verify the ingest actually succeeded:A 200 response from the ingest endpoint does not always mean memories were written — an AUDN-SC decision of no_op means the content was evaluated but no new memory was stored because it was already known. Check the ingest response body for the mutation decision.List records directly to confirm they exist:

atomicmemory list --user alice

If records appear in the list but not in search results, the query may not be semantically similar enough to the stored content. Try a more literal query that matches the ingested text closely.