Agentic Memory

Troubleshooting

Common issues and how to fix them.

Neo4j Connection Refused

If you see ServiceUnavailable: Unable to connect to bolt://localhost:7687:

  • Make sure Neo4j is running: docker ps | grep neo4j
  • Start it if needed: docker-compose up -d neo4j
  • Verify the port isn't blocked by a firewall.

Embedding API Key Errors

If indexing fails with an API key error:

  • Set GEMINI_API_KEY or GOOGLE_API_KEY
  • If using OpenAI for code embeddings, set CODE_EMBEDDING_PROVIDER=openai and OPENAI_API_KEY

MCP Server Not Found by Clients

If Claude or Cursor can't connect:

  • Verify the server is running: agentic-memory serve
  • Check if port 8000 is in use: lsof -i :8000
  • Try a different port: agentic-memory serve --port 3000
  • Validate your client config JSON syntax.

Semantic Search Returns Poor Results

If search results don't match your query:

  • Verify your embedding API key is set correctly.
  • Check that chunks exist in Neo4j: MATCH (ch:Chunk) RETURN count(ch)
  • Re-index if you recently changed the embedding provider.

Out of Memory During Indexing

For large codebases:

  • Increase Neo4j heap size: NEO4J_dbms_memory_heap_max__size=4G
  • Reduce indexed file extensions in .codememory/config.json
  • Use agentic-memory watch for incremental updates instead of full re-indexes.