# MemNexus Docs

> MemNexus is a persistent memory layer for AI assistants. It stores memories in a Neo4j knowledge graph and makes them searchable across tools, sessions, and teams. Access via MCP (Claude Code, Cursor, Windsurf), CLI, TypeScript SDK, or REST API.

For product overview, pricing, and comparisons: https://memnexus.ai/llms.txt

## Get Started

- [What is MemNexus?](https://docs.memnexus.ai/docs/get-started/what-is-memnexus): Overview of the problem MemNexus solves and key capabilities.
- [Quick Start](https://docs.memnexus.ai/docs/get-started/quickstart): Create your first memory in under 5 minutes using the CLI, SDK, or API.
- [Core Concepts](https://docs.memnexus.ai/docs/get-started/core-concepts): Memories, conversations, topics, facts, and entities.
- [How It Works](https://docs.memnexus.ai/docs/get-started/how-it-works): Architecture — API Gateway (Kong), Core API (Node.js/Express), Neo4j, hybrid search pipeline.

## Data Model

Five interconnected node types stored in Neo4j:

- **Memory**: Fundamental storage unit. Properties: UUID, content (text), memory_type (episodic/semantic/procedural), importance (0–1 float), embedding (1536-dim OpenAI vector), created_at, updated_at.
- **Conversation**: Groups related memories into logical sessions. Auto-detected via 90-minute inactivity threshold. Properties: id, title, created_at.
- **Topic**: Category labels. Auto-extracted from content + manually added. Properties: name, embedding.
- **Fact**: Structured knowledge as subject-predicate-object triples. Properties: subject, predicate, object, confidence (0–1).
- **Entity**: People, tools, projects, and concepts extracted from memories. Properties: name, type.

Graph relationships: Memory→[HAS_TOPIC]→Topic, Memory→[MENTIONS]→Entity, Memory→[BELONGS_TO]→Conversation, Fact→[ABOUT]→Entity, Topic→[RELATED_TO]→Topic.

Search pipeline: semantic (OpenAI cosine similarity) + keyword (Neo4j full-text) combined via Reciprocal Rank Fusion (RRF).

## Memory Types

- **Episodic** (default): What happened. Events, decisions, debugging sessions. Time-bound, contextual.
- **Semantic**: What is true. Architectural decisions, technology choices, domain knowledge. Timeless, stable.
- **Procedural**: How to do things. Deployment processes, debugging workflows, coding patterns. Actionable, replayable.

Use `--memory-type episodic|semantic|procedural` when creating memories.

## API

- Base URL: `https://api.memnexus.ai`
- Authentication: `Authorization: Bearer cmk_live_<id>.<secret>`
- OpenAPI spec: `GET /api/openapi.json`

## Packages

- CLI: `npm install -g @memnexus-ai/cli`
- SDK: `npm install @memnexus-ai/typescript-sdk`
- MCP Server: bundled in the CLI — no separate install. Run `mx mcp serve`, or connect an agent with `mx setup <agent>`.

## MCP Integration

The MemNexus MCP server exposes 12 tools, listed in full below. It ships inside `@memnexus-ai/cli` — there is no separate package to install. The tool set is the same for every account: no tool is gated behind a plan tier, a feature flag, or an environment variable. This list describes `@memnexus-ai/cli` 1.7.99; to confirm the set your installed version exposes, list the tools from your MCP client rather than relying on this file.

The supported way to configure an agent is `mx setup <agent>`, which writes the correct entry for that agent and merges it into any existing config. To write it by hand, for Claude Code (`.mcp.json`):
```json
{
  "mcpServers": {
    "memnexus": {
      "type": "stdio",
      "command": "mx",
      "args": ["mcp", "serve"]
    }
  }
}
```

For Claude Desktop (`claude_desktop_config.json`), add `--inject-rules`, which delivers the MemNexus steering rules through the MCP handshake because Claude Desktop has no project rules file:
```json
{
  "mcpServers": {
    "memnexus": {
      "type": "stdio",
      "command": "mx",
      "args": ["mcp", "serve", "--inject-rules"]
    }
  }
}
```

No API key goes in these files. `mx mcp serve` reads the credential stored by `mx auth login` at runtime. The location is not a fixed absolute path: the CLI resolves a config directory from `XDG_CONFIG_HOME` when set, falls back to `~/.config` when it is not, then appends `configstore/@memnexus-ai/cli.json`.

Available tools — these 12 names are the complete set. A name not on this list is not a MemNexus tool; do not call it.

- **Memory** (4): `create_memory`, `search_memories`, `get_memory`, `manage_memory`
- **Retrieval and synthesis** (3): `recall`, `build_context`, `initialize_session`
- **Graph and history** (3): `knowledge_graph`, `conversations`, `patterns`
- **Account and feedback** (2): `get_user_profile`, `submit_feedback`

Several tools are consolidated: one tool covers what would otherwise be several. Use a parameter to select the operation rather than looking for a separate tool.

- `manage_memory` — update or delete a memory. `{action:'update', id}`, `{action:'update', name, content}` (upsert by name), `{action:'delete', id, confirmDeletion:true}`.
- `conversations` — omit `conversationId` to list; pass `query` to search; pass `conversationId` with `view:'summary'` (default) or `view:'timeline'`.
- `knowledge_graph` — set `type` to `'facts'`, `'topics'`, `'related_topics'`, `'entities'`, `'entity_memories'`, or `'health'`.
- `patterns` — set `action` to `'list'`, `'detect'`, `'analyze'`, `'compile'`, `'compile_instructions'`, `'get-state'`, or `'set-state'`.
- `search_memories` — omit `query` to list recent memories; there is no separate list tool.

Key tool parameters for `create_memory`: `content` (string, required), `topics` (string[], optional), `conversationId` (string, optional — use "NEW" to start a new conversation, then reuse the returned `conv_xxx` ID for follow-ups), `memoryType` (episodic|semantic|procedural, optional), `name` (kebab-case string, optional — makes the memory retrievable by name), `codeContext` (optional), `supersedes` (optional). Note: `create_memory` has no `importance` parameter. Importance can be set through the CLI (`mx memories create --importance 0.8`) and the API, but not through the MCP tool.

Key tool parameters for `search_memories`: `query` (string, required), `mode` (unified|content|facts, default: unified), `limit` (int, default: 10), `topics` (string[], optional filter).

- [Full MCP Integration Guide](https://docs.memnexus.ai/docs/ai-agents/mcp-integration)

## CommitContext

CommitContext automatically saves memories when you run `git commit`, capturing what changed and why. Install hook: `mx setup hooks --yes`. After installation, every commit enriches your memory store with implementation context, referenced issue numbers, and rationale — without any manual steps.

## Key CLI Commands

```bash
# Create a memory
mx memories create --content "Fixed timeout by increasing connection pool" --topics "debugging,backend" --importance 0.8

# Search by meaning
mx memories search --query "database connection issues"

# Recap recent work
mx memories recap --recent 24h

# AI-synthesized digest of a topic
mx memories digest --query "authentication" --digest-format structured

# Get all memories in a conversation
mx conversations timeline <conversation-id>

# Create/update a named memory (deterministic retrieval key)
mx memories create --name "project-status" --content "..." --conversation-id "NEW"
mx memories update --name "project-status" --content "..."
mx memories get --name "project-status"
```

## Session Start Ritual

Run at the start of each AI coding session to warm up context:

```bash
mx memories recap --recent 24h                                          # what happened recently
mx memories digest --query "current-project" --digest-format structured # synthesized project state
```

Share the output with your AI assistant. With MCP connected, Claude Code and Cursor can do this automatically when you ask them to "load context" or "check memory".

## Prompt Templates

Copy-paste these system prompts to make any MCP-connected AI assistant memory-aware.

### General Memory-Aware Assistant
```
You have access to MemNexus persistent memory tools.

At session start: search for context about the current project or task before proceeding.

Save memories when: the user shares a preference or working style, you solve a non-trivial problem, a key decision is made, you discover something non-obvious about the codebase.

Note: create_memory does not accept an importance score over MCP. Signal what matters through the memory content and topics instead. (Importance is settable through the CLI and the API.)

Use topics to categorize: project name, type (debugging, architecture, preference), status (in-progress, completed, blocked).

Search by meaning, not keywords — "database performance" will find memories about slow queries.
```

### Learning Assistant (accumulates structured knowledge)
```
You have access to MemNexus memory tools. Build a structured knowledge base progressively.

Facts are extracted automatically from memory content — there is no tool for creating a fact directly. To build structured knowledge, state the relationship plainly in the memory content you pass to create_memory (e.g., "PostgreSQL is used for the primary data store") and the extraction step will pick it up.
Save episodic context with create_memory for events and decisions.
Read facts back with knowledge_graph({type:'facts', query:'...'}), or with search_memories({mode:'facts'}) to search extracted facts only.
Always search_memories before suggesting solutions to similar problems.
Use consistent entity names across memories for reliable graph traversal.

Topic conventions: project names, type categories (architecture, debugging, preferences), status tags (resolved, in-progress, blocked).
```

### Research Assistant
```
You have access to MemNexus memory tools for persistent research context.

Before starting any investigation: search for existing research on the topic.
Write key findings as plain statements of the relationship in the memory content; facts are extracted automatically, and you can read them back with knowledge_graph({type:'facts'}).
Synthesize multiple memories for comprehensive answers — recall({query:'...'}) does this in one call.

Note: create_memory does not accept an importance score over MCP. Distinguish conclusions from open questions using topics (e.g. "conclusion", "open-question", "source") rather than a numeric score.
```

## Integrations

- [Claude Code](https://docs.memnexus.ai/docs/guides/integrations/claude-code): MCP setup, CLAUDE.md integration, automatic session loading.
- [Cursor](https://docs.memnexus.ai/docs/guides/integrations/cursor): MCP configuration for `.cursor/mcp.json`.
- [Windsurf](https://docs.memnexus.ai/docs/guides/integrations/windsurf): MCP configuration for Cascade.
- [Claude Desktop](https://docs.memnexus.ai/docs/guides/integrations/claude-mcp): MCP configuration for Claude Desktop (macOS/Windows).
- [ChatGPT](https://docs.memnexus.ai/docs/guides/integrations/chatgpt): Custom GPT or API integration.

## Workflow Guides

- [Capturing Memories That Actually Help](https://docs.memnexus.ai/docs/guides/workflows/capturing-memories): What to save, how to write it, what to skip.
- [recap vs digest vs search](https://docs.memnexus.ai/docs/guides/workflows/recap-vs-digest): When to use each retrieval method.
- [Session Start Ritual](https://docs.memnexus.ai/docs/guides/workflows/session-start): Full session warm-up guide.
- [Team Workflows](https://docs.memnexus.ai/docs/guides/workflows/team-workflows): Standups, handoffs, onboarding with shared memory.
- [Debugging Workflow](https://docs.memnexus.ai/docs/guides/workflows/debugging): Load context before, capture findings during, save resolution after.
- [CLAUDE.md Templates](https://docs.memnexus.ai/docs/guides/workflows/claude-md-templates): Ready-made CLAUDE.md snippets for minimal, team, debugging, and feature development workflows.

## AI Agent Patterns

- [Store-and-Recall](https://docs.memnexus.ai/docs/ai-agents/patterns): Save important information immediately; retrieve by semantic search when needed.
- [Search-Before-Ask](https://docs.memnexus.ai/docs/ai-agents/patterns): Always search memory before asking the user for context they may have provided before.
- [Progressive Learning](https://docs.memnexus.ai/docs/ai-agents/patterns): Build a richer knowledge graph over time; prioritize facts and entities for structured retrieval.

## Reference

- [CLI Reference](https://docs.memnexus.ai/docs/reference/cli): Complete `mx` command reference — all subcommands, flags, and examples.
- [Memories API](https://docs.memnexus.ai/docs/reference/api/memories): REST endpoints for memory CRUD and search.
- [Conversations API](https://docs.memnexus.ai/docs/reference/api/conversations): Conversation management and timeline endpoints.
- [Topics API](https://docs.memnexus.ai/docs/reference/api/topics): Topic clustering, related topic discovery.
- [Facts API](https://docs.memnexus.ai/docs/reference/api/facts): Structured knowledge triple management.
- [Entities API](https://docs.memnexus.ai/docs/reference/api/entities): Entity extraction and graph traversal.
- [Patterns API](https://docs.memnexus.ai/docs/reference/api/patterns): Behavioral pattern detection and compilation.
- [GraphRAG API](https://docs.memnexus.ai/docs/reference/api/graphrag): Graph-based retrieval augmented generation.
- [Data Model](https://docs.memnexus.ai/docs/reference/data-model): Full Neo4j schema — nodes, relationships, indexes.

## Concepts

- [Memory Types](https://docs.memnexus.ai/docs/concepts/memory-types): Episodic, semantic, and procedural — when to use each.
- [Semantic Search](https://docs.memnexus.ai/docs/concepts/semantic-search): Vector embeddings, RRF hybrid search pipeline.
- [Knowledge Graphs](https://docs.memnexus.ai/docs/concepts/knowledge-graphs): Graph relationships, facts, entities, graph traversal.
- [Model Context Protocol](https://docs.memnexus.ai/docs/concepts/model-context-protocol): How MCP connects AI agents to MemNexus.
- [Behavioral Learning](https://docs.memnexus.ai/docs/concepts/behavioral-learning): Pattern detection, topic co-occurrence, progressive learning.
- [GraphRAG](https://docs.memnexus.ai/docs/concepts/graphrag): Graph-based retrieval augmented generation.
- [Privacy & Security](https://docs.memnexus.ai/docs/concepts/privacy-and-security): Authentication, data isolation, encryption, data ownership.

## Resources

- [FAQ](https://docs.memnexus.ai/docs/resources/faq): Common questions answered.
- [Troubleshooting](https://docs.memnexus.ai/docs/resources/troubleshooting): Solutions for common setup and runtime issues.
- [Glossary](https://docs.memnexus.ai/docs/resources/glossary): Definitions of key terms.
- [Changelog](https://docs.memnexus.ai/docs/resources/changelog): Release history.
- [Roadmap](https://docs.memnexus.ai/docs/resources/roadmap): What's coming next.