claude-code-agentic-semantic-memory-system

This MCP server implements a persistent semantic memory system for Claude Code, enabling long-term storage and retrieval of memories across sessions. It provides tools for creating memories, performing semantic searches, listing memories, updating or deleting entries, and organizing memories into project namespaces. The system stores data in a PostgreSQL database (with pgvector support) and generates embeddings locally, so it can operate offline without external API dependencies. With memory relations and project namespaces, you can build a structured knowledge graph of user preferences, requirements, and context that Claude Code can reference over time.

To use it, ensure the server is running and properly connected to your PostgreSQL database. The server exposes a set of MCP tools such as create_memory, search_memory, list_memories, delete_memory, update_memory, switch_project, list_projects, and delete_project. These tools are invoked by Claude Code through the MCP interface and can store high-signal information that is immutable (append-only) unless explicitly updated via the appropriate workflow. You can also manage memory namespaces (projects) to keep contexts separate when working on multiple tasks or clients.

In Claude Code, add the MCP server as agentic-memory and point it to the run-server script (as shown in the quick-start steps). Once connected, you can perform semantic memory operations, run local embeddings, and query memories using natural language prompts to drive tool invocations. The combination of local embeddings, semantic search, and relational memories enables richer context retention and retrieval across sessions.

Prerequisites:

• Node.js 18+ and npm
• A PostgreSQL database with pgvector support (Neon recommended)
• Claude Code CLI installed

Step-by-step installation:

1. Clone or copy the MCP server into your project and install dependencies

# From your project root
cp -r /path/to/agentic-memory /your/project/.claude/mcp-servers/
cd /your/project/.claude/mcp-servers/agentic-memory
npm install

2. Configure environment variables

cp .env.example .env
# Edit .env with your database URL and optional settings

3. Ensure database migrations run

npm run db:migrate

4. Start the MCP server (using the provided run script or your preferred start command)

# If you use the included script, ensure it is executable
bash ./run-server.sh
# Alternatively, you can start via Node if your setup uses the TS entry point
# npm run start

5. Register the MCP server with Claude Code

claude mcp add agentic-memory ./run-server.sh

6. Verify the server connection

claude mcp list
# Should show: agentic-memory - ✓ Connected

Notes:

• If you adjust environment variables, restart the server for changes to take effect.
• Ensure the PostgreSQL database is accessible from the environment running the MCP server.

Tips and common issues:

• If you encounter connection errors, verify DATABASE_URL in .env matches your database and that the database is accessible from the host running the MCP server.
• Ensure the pgvector extension is installed in your PostgreSQL instance and that migrations have run so the memories and relations tables exist.
• Embedding configuration is optional; the system ships with a local embedding implementation. You can switch to alternate embedding models by adjusting EMBEDDING_MODEL and EMBEDDING_DIMENSIONS in the environment.
• For production deployments, consider enabling database backups, connection pooling, and monitoring of memory search latency.
• When adding to Claude Code, reference the correct path to the run script if you customize your startup process.
• Remember: memories should be immutable after creation; use update_memory only for legitimate corrections, and prefer append-only semantics where possible.