diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5eb886c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,1186 @@
+# CLAUDE.md - AI Assistant Guide for A-MEM
+
+> **Last Updated:** December 1, 2025
+> **Version:** 1.0
+> **Purpose:** Comprehensive guide for AI assistants working with the A-MEM codebase
+
+---
+
+## 📋 Table of Contents
+
+1. [Project Overview](#project-overview)
+2. [Architecture & Design Principles](#architecture--design-principles)
+3. [Directory Structure](#directory-structure)
+4. [Key Components & Modules](#key-components--modules)
+5. [Development Workflows](#development-workflows)
+6. [Configuration & Environment](#configuration--environment)
+7. [MCP Server Integration](#mcp-server-integration)
+8. [Testing Strategy](#testing-strategy)
+9. [Common Tasks & Patterns](#common-tasks--patterns)
+10. [Best Practices & Conventions](#best-practices--conventions)
+11. [Troubleshooting Guide](#troubleshooting-guide)
+
+---
+
+## 🎯 Project Overview
+
+### What is A-MEM?
+
+**A-MEM** (Agentic Memory) is an **MCP-integrated memory system** for LLM agents based on the **Zettelkasten principle**. It provides persistent, graph-based memory with semantic retrieval capabilities for AI assistants in IDE environments (Cursor, VSCode).
+
+### Research Foundation
+
+Based on the paper: ["A-Mem: Agentic Memory for LLM Agents"](https://arxiv.org/html/2502.12110v11)
+Authors: Wujiang Xu, Zujie Liang, Kai Mei, Hang Gao, Juntao Tan, Yongfeng Zhang
+
+### Key Differentiators
+
+This implementation focuses on:
+- **MCP Protocol Integration** for IDE environments
+- **Explicit Graph-Based Memory Linking** with typed edges, reasoning, and weights
+- **Dual Storage Architecture**: ChromaDB (vector similarity) + Graph Backend (NetworkX/RustworkX/FalkorDB)
+- **Autonomous Maintenance**: Memory Enzymes for graph health
+- **Research Integration**: Web research agent for JIT context optimization
+
+---
+
+## 🏗️ Architecture & Design Principles
+
+### Core Architecture Patterns
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      MCP Server Layer                        │
+│              (src/a_mem/main.py - stdio_server)             │
+└───────────────────────┬─────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  Memory Controller Layer                     │
+│              (src/a_mem/core/logic.py)                      │
+│  • Async I/O via run_in_executor                            │
+│  • Background evolution tasks                                │
+│  • Enzyme scheduler orchestration                           │
+└───────────┬─────────────────────────┬───────────────────────┘
+            │                         │
+            ▼                         ▼
+┌───────────────────────┐  ┌──────────────────────────────────┐
+│   Storage Layer       │  │      LLM Service Layer           │
+│  (storage/engine.py)  │  │     (utils/llm.py)               │
+│                       │  │                                  │
+│  • GraphStore         │  │  • Metadata extraction           │
+│  • VectorStore        │  │  • Embedding generation          │
+│  • Cross-platform     │  │  • Multi-provider support        │
+│    file locking       │  │    (Ollama/OpenRouter)           │
+└───────────────────────┘  └──────────────────────────────────┘
+```
+
+### Design Principles
+
+1. **Async Non-Blocking I/O**
+   - All blocking operations use `asyncio.run_in_executor`
+   - Background tasks for evolution and maintenance
+   - Parallel HTTP server for external tool access
+
+2. **Dual Storage Architecture**
+   - **Vector Store (ChromaDB)**: Semantic similarity search
+   - **Graph Store**: Explicit typed relationships with reasoning
+   - Enables hybrid retrieval: similarity + graph traversal
+
+3. **Graph Backend Flexibility**
+   - **NetworkX** (default): Cross-platform, no extra dependencies
+   - **RustworkX** (performance): 3x-100x faster, Windows-compatible
+   - **FalkorDB** (experimental): Persistent storage, Redis-based
+
+4. **Type Safety with Pydantic**
+   - All data models use Pydantic BaseModel
+   - Automatic validation and serialization
+   - Type hints throughout codebase
+
+5. **Event-Driven Architecture**
+   - JSONL event log for audit trail (`data/events.jsonl`)
+   - All critical operations logged
+   - Enables debugging and analytics
+
+---
+
+## 📁 Directory Structure
+
+```
+a-mem-mcp-server/
+├── src/
+│   └── a_mem/
+│       ├── __init__.py
+│       ├── main.py                    # MCP server entry point
+│       ├── config.py                  # Configuration & environment
+│       ├── models/
+│       │   ├── __init__.py
+│       │   └── note.py                # Data models (AtomicNote, NoteInput, etc.)
+│       ├── core/
+│       │   ├── __init__.py
+│       │   └── logic.py               # MemoryController (core business logic)
+│       ├── storage/
+│       │   ├── __init__.py
+│       │   ├── engine.py              # StorageManager, GraphStore, VectorStore
+│       │   ├── rustworkx_store.py     # RustworkX graph backend
+│       │   ├── falkordb_store.py      # FalkorDB graph backend (Linux/macOS)
+│       │   ├── falkordb_store_windows.py  # FalkorDB Windows adapter
+│       │   └── safe_graph_wrapper.py  # Edge case handling wrapper
+│       └── utils/
+│           ├── __init__.py
+│           ├── llm.py                 # LLM service (metadata, embeddings)
+│           ├── priority.py            # Priority scoring & event logging
+│           ├── enzymes.py             # Memory maintenance (14+ operations)
+│           ├── researcher.py          # Web research agent
+│           ├── researcher_tools.py    # HTTP-based research tools
+│           ├── validation.py          # MCP parameter validation
+│           └── serializers.py         # Data serialization helpers
+├── tests/                             # Test suite (24+ tests)
+│   ├── test_a_mem.py                 # Core functionality tests
+│   ├── test_code_structure.py        # Structure validation
+│   ├── test_new_features.py          # Type classification, priority, events
+│   ├── test_enzymes.py               # Memory enzymes tests
+│   ├── test_scheduler.py             # Scheduler tests
+│   ├── test_mcp_integration.py       # MCP server integration tests
+│   └── test_researcher*.py           # Researcher agent tests
+├── tools/                             # Standalone utilities
+│   ├── amem_stats.py                 # CLI status tool (like git status)
+│   ├── visualize_memory.py           # Web-based graph dashboard
+│   ├── extract_graph.py              # Graph data extractor
+│   └── a_mem_cli.py                  # Command-line interface
+├── docs/                              # Extended documentation
+│   ├── MEMORY_ENZYMES_DETAILED.md    # Enzyme documentation
+│   ├── RESEARCHER_AGENT_DETAILED.md  # Research agent guide
+│   ├── TEST_REPORT.md                # Test results
+│   ├── MCP_SERVER_TEST_REPORT.md     # MCP integration tests
+│   └── *.svg                         # Architecture diagrams
+├── data/                              # Runtime data (auto-created)
+│   ├── chroma/                       # ChromaDB vector store
+│   ├── graph/
+│   │   ├── knowledge_graph.json      # Graph snapshot (NetworkX)
+│   │   ├── knowledge_graph.graphml   # Graph snapshot (RustworkX)
+│   │   └── graph.lock                # Cross-platform file lock
+│   └── events.jsonl                  # Event log (append-only)
+├── .env.example                       # Configuration template
+├── requirements.txt                   # Python dependencies
+├── mcp_server.py                      # MCP server launcher
+├── README.md                          # User documentation
+├── MCP_SERVER_SETUP.md               # MCP setup guide
+└── CLAUDE.md                          # This file (AI assistant guide)
+```
+
+### Key Files to Understand
+
+| File | Purpose | Key Classes/Functions |
+|------|---------|----------------------|
+| `src/a_mem/main.py` | MCP server implementation | `list_tools()`, `call_tool()`, `main()` |
+| `src/a_mem/core/logic.py` | Core business logic | `MemoryController`, `create_note()`, `retrieve()` |
+| `src/a_mem/storage/engine.py` | Storage layer | `StorageManager`, `GraphStore`, `VectorStore` |
+| `src/a_mem/utils/llm.py` | LLM integration | `LLMService`, `extract_metadata()`, `get_embedding()` |
+| `src/a_mem/utils/enzymes.py` | Memory maintenance | `run_memory_enzymes()`, 14+ enzyme functions |
+| `src/a_mem/models/note.py` | Data models | `AtomicNote`, `NoteInput`, `NoteRelation` |
+| `src/a_mem/config.py` | Configuration | `Config` class, environment variables |
+
+---
+
+## 🔧 Key Components & Modules
+
+### 1. MCP Server (`src/a_mem/main.py`)
+
+**Purpose:** JSON-RPC server implementing Model Context Protocol (MCP)
+
+**Key Functions:**
+- `list_tools()` - Returns 15 available MCP tools
+- `call_tool(name, arguments)` - Routes tool calls to controller
+- `main()` - Server initialization, enzyme scheduler, HTTP server
+
+**15 MCP Tools:**
+1. `create_atomic_note` - Store new memory
+2. `retrieve_memories` - Semantic search with priority
+3. `get_memory_stats` - System statistics
+4. `add_file` - Import file with chunking
+5. `reset_memory` - Clear all data
+6. `list_notes` - List all notes
+7. `get_note` - Get single note by ID
+8. `update_note` - Update note metadata
+9. `delete_atomic_note` - Delete note
+10. `list_relations` - List graph edges
+11. `add_relation` - Manual edge creation
+12. `remove_relation` - Delete edge
+13. `get_graph` - Full graph snapshot
+14. `run_memory_enzymes` - Manual maintenance
+15. `research_and_store` - Web research + storage
+
+**Communication:**
+- Uses `stdio_server` for IDE integration
+- Logs to stderr (not stdout) to avoid breaking JSON-RPC
+- Optional HTTP server on port 42424 for external tools
+
+### 2. Memory Controller (`src/a_mem/core/logic.py`)
+
+**Purpose:** Orchestrates memory operations with async I/O
+
+**Key Methods:**
+
+```python
+class MemoryController:
+    async def create_note(input_data: NoteInput) -> str:
+        """
+        1. Extract metadata via LLM (or use pre-provided)
+        2. Generate embedding (concat: content + summary + keywords + tags)
+        3. Store in vector DB + graph
+        4. Log event
+        5. Background evolution task
+        """
+
+    async def retrieve(query: str) -> List[SearchResult]:
+        """
+        1. Search vector DB for similar notes
+        2. Compute priority scores (type + age + usage + edges)
+        3. Traverse graph for connected notes
+        4. Sort by combined score (similarity × priority)
+        5. Return with context
+        """
+
+    async def _evolve_memory(note, embedding):
+        """
+        Background task:
+        1. Find similar notes (cosine similarity)
+        2. Create typed edges with reasoning
+        3. Check for existing notes to merge/update
+        4. Log evolution events
+        """
+```
+
+**Async Pattern:**
+```python
+# All blocking I/O uses run_in_executor
+loop = asyncio.get_running_loop()
+result = await loop.run_in_executor(None, blocking_function, args)
+```
+
+### 3. Storage Layer (`src/a_mem/storage/engine.py`)
+
+**GraphStore:**
+```python
+class GraphStore:
+    def __init__(self):
+        self.graph = nx.DiGraph()  # Or RustworkX/FalkorDB
+        self.load()
+
+    def add_node(self, note: AtomicNote):
+        """Store node with all metadata"""
+
+    def add_edge(self, source, target, relation_type, reasoning, weight):
+        """Create typed edge with reasoning"""
+
+    def save_snapshot(self):
+        """Atomic save with temp file + rename"""
+```
+
+**VectorStore:**
+```python
+class VectorStore:
+    def __init__(self):
+        self.client = chromadb.PersistentClient(path=settings.CHROMA_DIR)
+        self.collection = self.client.get_or_create_collection("a_mem_notes")
+
+    def add(self, note: AtomicNote, embedding: List[float]):
+        """Store with metadata for filtering"""
+
+    def search(self, query_embedding, max_results=10):
+        """Cosine similarity search"""
+```
+
+**Cross-Platform File Locking:**
+- Uses `fcntl` on Linux/macOS
+- Falls back to `portalocker` on Windows
+- Prevents concurrent write conflicts
+
+### 4. LLM Service (`src/a_mem/utils/llm.py`)
+
+**Multi-Provider Support:**
+
+```python
+class LLMService:
+    def __init__(self):
+        self.provider = settings.LLM_PROVIDER  # "ollama" or "openrouter"
+
+    def extract_metadata(self, content: str) -> dict:
+        """
+        Extracts:
+        - contextual_summary
+        - keywords (max 7)
+        - tags
+        - type (rule/procedure/concept/tool/reference/integration)
+        """
+
+    def get_embedding(self, text: str) -> List[float]:
+        """Generate embedding vector"""
+
+    def refine_summary(self, content: str, old_summary: str) -> str:
+        """Make similar summaries more specific"""
+```
+
+**Provider Configuration:**
+- **Ollama** (local): HTTP requests to localhost:11434
+- **OpenRouter** (cloud): API key-based, OpenAI-compatible
+
+### 5. Memory Enzymes (`src/a_mem/utils/enzymes.py`)
+
+**14+ Autonomous Maintenance Operations:**
+
+```python
+def run_memory_enzymes(graph, llm, prune_config, suggest_config, refine_config):
+    """
+    1. Link Pruner: Remove old/weak edges (age > 90 days, weight < 0.3)
+    2. Zombie Node Remover: Delete empty nodes
+    3. Duplicate Merger: Find and merge exact/semantic duplicates
+    4. Edge Validator: Fix edges (add reasoning, standardize types)
+    5. Self-Loop Remover: Remove self-referential edges
+    6. Isolated Node Finder: Identify unconnected nodes
+    7. Isolated Node Linker: Auto-link isolated nodes (similarity ≥ 0.70)
+    8. Keyword Normalizer: Clean and limit keywords (max 7)
+    9. Quality Score Calculator: Score notes by content/metadata/connections
+    10. Note Validator: Validate and correct missing fields
+    11. Low Quality Note Remover: Remove CAPTCHA/error/spam pages
+    12. Summary Refiner: Make similar summaries more distinct
+    13. Corrupted Node Repairer: Fix nodes with invalid data
+    14. Relation Suggester: Find semantic connections (similarity ≥ 0.75)
+    15. Summary Digester: Compress nodes with >8 children
+    """
+```
+
+**Scheduler:**
+- Runs automatically every hour (configurable)
+- Auto-saves graph every 5 minutes
+- Graceful error handling
+
+### 6. Research Agent (`src/a_mem/utils/researcher.py`)
+
+**Purpose:** JIT web research for low-confidence queries
+
+**Workflow:**
+```python
+class ResearcherAgent:
+    async def research(query: str, context: str) -> List[AtomicNote]:
+        """
+        1. Search web (Google Search API or DuckDuckGo)
+        2. Extract top N URLs
+        3. Fetch content:
+           - Web pages: Jina Reader (local/cloud) or Readability
+           - PDFs: Unstructured (library/API)
+        4. Parse and clean content
+        5. Extract metadata via LLM
+        6. Create AtomicNote objects
+        7. Return for storage
+        """
+```
+
+**Hybrid Tool Strategy:**
+- **Primary**: MCP tools (if available via callback)
+- **Fallback**: HTTP-based tools (Google API, DuckDuckGo, Jina Reader)
+
+**Configuration:**
+```bash
+RESEARCHER_ENABLED=true
+RESEARCHER_CONFIDENCE_THRESHOLD=0.5  # Auto-trigger when score < 0.5
+RESEARCHER_MAX_SOURCES=5
+GOOGLE_SEARCH_ENABLED=true
+JINA_READER_ENABLED=true
+UNSTRUCTURED_ENABLED=true
+```
+
+### 7. Data Models (`src/a_mem/models/note.py`)
+
+**Core Models:**
+
+```python
+class AtomicNote(BaseModel):
+    id: str                          # UUID
+    content: str                     # Original text
+    contextual_summary: str          # LLM-generated summary
+    keywords: List[str]              # Max 7 keywords
+    tags: List[str]                  # Categorical tags
+    created_at: datetime             # Timestamp
+    type: Optional[str]              # rule/procedure/concept/tool/reference/integration
+    metadata: Dict[str, Any]         # Experimental fields
+
+class NoteInput(BaseModel):
+    content: str
+    source: Optional[str] = "user_input"
+    # Pre-extracted metadata (optional, from ResearcherAgent)
+    contextual_summary: Optional[str] = None
+    keywords: Optional[List[str]] = None
+    tags: Optional[List[str]] = None
+    type: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+class NoteRelation(BaseModel):
+    source_id: str
+    target_id: str
+    relation_type: str               # relates_to/contradicts/supports/etc.
+    reasoning: Optional[str]         # Why this relation exists
+    weight: float = 1.0              # 0.0-1.0
+    created_at: datetime
+
+class SearchResult(BaseModel):
+    note: AtomicNote
+    score: float                     # Combined similarity × priority
+    related_notes: List[AtomicNote]  # Graph-connected notes
+```
+
+---
+
+## 🔄 Development Workflows
+
+### Adding a New MCP Tool
+
+1. **Define tool schema** in `main.py:list_tools()`:
+```python
+Tool(
+    name="my_new_tool",
+    description="Clear description for AI assistants",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "param1": {"type": "string", "description": "..."},
+        },
+        "required": ["param1"]
+    }
+)
+```
+
+2. **Add handler** in `main.py:call_tool()`:
+```python
+elif name == "my_new_tool":
+    param1 = arguments.get("param1", "")
+    result = await controller.my_method(param1)
+    return [TextContent(type="text", text=json.dumps(result, indent=2))]
+```
+
+3. **Implement logic** in `core/logic.py`:
+```python
+async def my_method(self, param1: str):
+    loop = asyncio.get_running_loop()
+    # Offload blocking I/O
+    result = await loop.run_in_executor(None, self._blocking_operation, param1)
+    return result
+```
+
+4. **Add tests** in `tests/test_mcp_server.py`
+
+### Modifying Storage Backend
+
+**GraphStore modifications:**
+- Edit `storage/engine.py` for NetworkX
+- Edit `storage/rustworkx_store.py` for RustworkX
+- Edit `storage/falkordb_store.py` for FalkorDB
+
+**Key methods to update:**
+```python
+def add_node(self, note: AtomicNote)
+def add_edge(self, source, target, relation_type, reasoning, weight)
+def get_neighbors(self, node_id) -> List[Tuple[str, dict]]
+def save_snapshot()
+def load()
+```
+
+**VectorStore modifications:**
+- Edit `storage/engine.py:VectorStore`
+- ChromaDB API: `add()`, `query()`, `delete()`
+
+### Adding a Memory Enzyme
+
+1. **Create enzyme function** in `utils/enzymes.py`:
+```python
+def my_enzyme(graph: GraphStore, llm: LLMService, config: dict) -> dict:
+    """
+    Args:
+        graph: GraphStore instance
+        llm: LLMService instance
+        config: Enzyme-specific configuration
+
+    Returns:
+        dict: Results with counts, lists, etc.
+    """
+    # Your logic here
+    log_event("MY_ENZYME_RUN", {"count": 42})
+    return {"count": 42}
+```
+
+2. **Add to enzyme runner** in `utils/enzymes.py:run_memory_enzymes()`:
+```python
+results["my_enzyme"] = my_enzyme(graph, llm, config)
+```
+
+3. **Add to MCP tool parameters** (optional) in `main.py`
+
+4. **Add tests** in `tests/test_enzymes.py`
+
+### Debugging with Event Logs
+
+**View recent events:**
+```bash
+tail -n 50 data/events.jsonl | jq .
+```
+
+**Filter by event type:**
+```bash
+grep "NOTE_CREATED" data/events.jsonl | jq .
+```
+
+**Event types:**
+- `NOTE_CREATED`, `RELATION_CREATED`, `MEMORY_EVOLVED`
+- `LINKS_PRUNED`, `RELATION_PRUNED`, `NODE_PRUNED`
+- `DUPLICATES_MERGED`, `SELF_LOOPS_REMOVED`
+- `ISOLATED_NODES_FOUND`, `ISOLATED_NODES_LINKED`
+- `KEYWORDS_NORMALIZED`, `QUALITY_SCORES_CALCULATED`
+- `NOTES_VALIDATED`, `LOW_QUALITY_NOTES_REMOVED`
+- `CORRUPTED_NODES_REPAIRED`, `RELATIONS_SUGGESTED`
+- `ENZYME_SCHEDULER_RUN`, `RESEARCHER_MANUAL_RUN`
+
+---
+
+## ⚙️ Configuration & Environment
+
+### Environment Variables (`.env` file)
+
+**LLM Provider:**
+```bash
+LLM_PROVIDER=ollama              # "ollama" or "openrouter"
+
+# Ollama (local)
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_LLM_MODEL=qwen3:4b
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text:latest
+
+# OpenRouter (cloud)
+OPENROUTER_API_KEY=your_key_here
+OPENROUTER_LLM_MODEL=openai/gpt-4o-mini
+OPENROUTER_EMBEDDING_MODEL=openai/text-embedding-3-small
+```
+
+**Graph Backend:**
+```bash
+GRAPH_BACKEND=networkx           # "networkx", "rustworkx", or "falkordb"
+```
+
+**Retrieval:**
+```bash
+MAX_NEIGHBORS=5                  # Max connected notes per result
+MIN_SIMILARITY_SCORE=0.4         # Minimum cosine similarity
+```
+
+**Research Agent:**
+```bash
+RESEARCHER_ENABLED=true
+RESEARCHER_CONFIDENCE_THRESHOLD=0.5
+RESEARCHER_MAX_SOURCES=5
+GOOGLE_SEARCH_ENABLED=true
+GOOGLE_API_KEY=your_key
+GOOGLE_SEARCH_ENGINE_ID=your_id
+JINA_READER_ENABLED=true
+UNSTRUCTURED_ENABLED=true
+```
+
+**HTTP Server (optional):**
+```bash
+TCP_SERVER_ENABLED=false         # Enable HTTP endpoint for tools
+TCP_SERVER_HOST=127.0.0.1
+TCP_SERVER_PORT=42424
+```
+
+### Configuration Hierarchy
+
+1. **Base:** `.env` file (default values)
+2. **Override:** MCP `env` block in `mcp.json`
+3. **Priority:** MCP env > .env file
+
+**Example MCP config with overrides:**
+```json
+{
+  "mcpServers": {
+    "a-mem": {
+      "command": "python",
+      "args": ["-m", "src.a_mem.main"],
+      "cwd": "/path/to/a-mem-mcp-server",
+      "env": {
+        "LLM_PROVIDER": "ollama",
+        "OLLAMA_LLM_MODEL": "llama3.2:3b",
+        "RESEARCHER_ENABLED": "true"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🔌 MCP Server Integration
+
+### MCP Protocol Basics
+
+**Communication:**
+- Uses **stdio** (stdin/stdout) for JSON-RPC messages
+- All logging must go to **stderr** (not stdout)
+- Server runs in background as subprocess
+
+**Helper function:**
+```python
+def log_debug(message: str):
+    """Logs to stderr to avoid breaking MCP JSON-RPC"""
+    print(message, file=sys.stderr)
+```
+
+### IDE Configuration
+
+**Cursor IDE:**
+```json
+{
+  "mcpServers": {
+    "a-mem": {
+      "command": "python",
+      "args": ["-m", "src.a_mem.main"],
+      "cwd": "/absolute/path/to/a-mem-mcp-server"
+    }
+  }
+}
+```
+
+**Location:**
+- Windows: `%USERPROFILE%\.cursor\mcp.json`
+- macOS/Linux: `~/.cursor/mcp.json`
+
+### Tool Usage Patterns
+
+**From AI assistant:**
+```
+User: "Remember this: Python uses asyncio for concurrent I/O"
+
+Assistant calls:
+{
+  "tool": "create_atomic_note",
+  "arguments": {
+    "content": "Python uses asyncio for concurrent I/O",
+    "source": "user_input"
+  }
+}
+
+Response:
+{
+  "status": "success",
+  "note_id": "732c8c3b-7c71-42a6-9534-a611b4ffe7bf",
+  "message": "Note created. Evolution started in background."
+}
+```
+
+**Retrieve:**
+```
+User: "What do you know about Python async?"
+
+Assistant calls:
+{
+  "tool": "retrieve_memories",
+  "arguments": {
+    "query": "Python async programming",
+    "max_results": 5
+  }
+}
+
+Response:
+{
+  "status": "success",
+  "results": [
+    {
+      "id": "...",
+      "content": "...",
+      "summary": "...",
+      "type": "concept",
+      "relevance_score": 0.87,
+      "connected_memories": 3,
+      "connected_context": "..."
+    }
+  ]
+}
+```
+
+### Parallel HTTP Server
+
+**When enabled** (`TCP_SERVER_ENABLED=true`):
+- MCP server runs on stdio
+- HTTP server runs on port 42424
+- Same `MemoryController` instance shared
+
+**Endpoint:**
+```bash
+curl http://127.0.0.1:42424/get_graph
+```
+
+**Use case:** External tools (visualizer, CLI) can access live graph without interfering with MCP protocol
+
+---
+
+## 🧪 Testing Strategy
+
+### Test Structure
+
+```
+tests/
+├── test_a_mem.py              # Core: create, retrieve, evolve
+├── test_code_structure.py     # Architecture validation
+├── test_new_features.py       # Type classification, priority, events
+├── test_enzymes.py            # All 14+ enzymes
+├── test_scheduler.py          # Automatic enzyme scheduling
+├── test_mcp_integration.py    # MCP server integration
+├── test_researcher*.py        # Research agent (live + mocked)
+├── test_safe_graph_wrapper.py # Edge case handling
+└── test_rustworkx*.py         # RustworkX backend
+```
+
+### Running Tests
+
+**All tests:**
+```bash
+python tests/test_a_mem.py
+python tests/test_code_structure.py
+python tests/test_new_features.py
+python tests/test_enzymes.py
+python tests/test_scheduler.py
+```
+
+**Single test:**
+```bash
+python -m pytest tests/test_a_mem.py::test_create_note -v
+```
+
+**With coverage:**
+```bash
+pytest --cov=src/a_mem tests/
+```
+
+### Test Conventions
+
+1. **Use temp directories** for test data
+2. **Clean up** after each test (`tearDown`)
+3. **Mock external services** (LLM, web requests)
+4. **Test both success and error paths**
+5. **Verify event logs** for critical operations
+
+**Example test:**
+```python
+def test_create_note(self):
+    note_input = NoteInput(
+        content="Test note",
+        source="test"
+    )
+    note_id = asyncio.run(self.controller.create_note(note_input))
+    self.assertIsNotNone(note_id)
+
+    # Verify storage
+    note = asyncio.run(self.controller.get_note_data(note_id))
+    self.assertEqual(note["content"], "Test note")
+
+    # Verify event log
+    events = self._read_events()
+    self.assertTrue(any(e["event_type"] == "NOTE_CREATED" for e in events))
+```
+
+---
+
+## 📝 Common Tasks & Patterns
+
+### Task 1: Add Support for a New LLM Provider
+
+1. **Update `utils/llm.py`:**
+```python
+def extract_metadata(self, content: str) -> dict:
+    if self.provider == "ollama":
+        # Existing Ollama logic
+    elif self.provider == "openrouter":
+        # Existing OpenRouter logic
+    elif self.provider == "new_provider":
+        # Your new provider logic
+```
+
+2. **Add config in `config.py`:**
+```python
+NEW_PROVIDER_API_KEY = os.getenv("NEW_PROVIDER_API_KEY", "")
+NEW_PROVIDER_LLM_MODEL = os.getenv("NEW_PROVIDER_LLM_MODEL", "default-model")
+```
+
+3. **Update `.env.example`**
+
+4. **Add tests** in `tests/test_llm.py`
+
+### Task 2: Optimize Graph Performance
+
+**Switch to RustworkX:**
+```bash
+pip install rustworkx
+```
+
+```bash
+# .env
+GRAPH_BACKEND=rustworkx
+```
+
+**Benchmark:**
+```bash
+python tools/benchmark_enzymes.py
+```
+
+**Expected speedup:** 3x-100x for large graphs (>1000 nodes)
+
+### Task 3: Visualize Memory Graph
+
+**Start visualizer:**
+```bash
+python tools/visualize_memory.py
+```
+
+**Open browser:** http://localhost:8050
+
+**Features:**
+- Interactive network graph (priority-based sizing, type-based coloring)
+- Priority statistics by type
+- Relation type distribution
+- Event timeline
+- Node details table
+
+**Update data:**
+```bash
+python tools/extract_graph.py  # Requires TCP_SERVER_ENABLED=true
+```
+
+### Task 4: Monitor System Health
+
+**Quick status:**
+```bash
+python tools/amem_stats.py
+```
+
+**Output:**
+```
+🧠 A-MEM Graph Status
+==================================================
+📝 Notes:        127
+🔗 Relations:    342
+📊 Notes by Type:
+   🔴 rule           23
+   🔵 procedure      45
+   🟢 concept        59
+⚙️  Last Enzyme Run: 15min ago
+==================================================
+```
+
+**Watch mode:**
+```bash
+python tools/amem_stats.py --watch
+```
+
+**Diff mode:**
+```bash
+python tools/amem_stats.py --diff
+# +12 notes | +28 relations | -5 zombie nodes
+```
+
+### Task 5: Manual Memory Maintenance
+
+**Via MCP:**
+```json
+{
+  "tool": "run_memory_enzymes",
+  "arguments": {
+    "prune_max_age_days": 90,
+    "prune_min_weight": 0.3,
+    "suggest_threshold": 0.75,
+    "auto_add_suggestions": false
+  }
+}
+```
+
+**Via CLI:**
+```bash
+python tools/a_mem_cli.py --enzyme-run
+```
+
+**Schedule:**
+- Automatic: Every hour (configurable in `main.py`)
+- Manual: Use tool or CLI
+
+---
+
+## ✅ Best Practices & Conventions
+
+### Code Style
+
+1. **Type hints everywhere:**
+```python
+def my_function(param: str) -> dict:
+    """Clear docstring."""
+    return {}
+```
+
+2. **Pydantic for data validation:**
+```python
+class MyModel(BaseModel):
+    field: str
+    optional_field: Optional[int] = None
+```
+
+3. **Async I/O for blocking operations:**
+```python
+loop = asyncio.get_running_loop()
+result = await loop.run_in_executor(None, blocking_func, args)
+```
+
+4. **Logging to stderr (not stdout):**
+```python
+print(message, file=sys.stderr)
+```
+
+### Error Handling
+
+**Graceful degradation:**
+```python
+try:
+    result = await risky_operation()
+except Exception as e:
+    log_debug(f"[ERROR] Operation failed: {e}")
+    return {"error": str(e), "status": "partial_success"}
+```
+
+**Return structured errors:**
+```python
+return {
+    "status": "error",
+    "error_code": "INVALID_INPUT",
+    "message": "Parameter X is required",
+    "details": {...}
+}
+```
+
+### Event Logging
+
+**Always log critical operations:**
+```python
+from .utils.priority import log_event
+
+log_event("OPERATION_NAME", {
+    "key": "value",
+    "timestamp": datetime.now().isoformat()
+})
+```
+
+### Data Persistence
+
+**Atomic saves:**
+```python
+temp_file = path.with_suffix(".tmp")
+with open(temp_file, 'w') as f:
+    json.dump(data, f)
+temp_file.rename(path)  # Atomic on POSIX
+```
+
+**Backup before destructive operations:**
+```python
+if path.exists():
+    backup = path.with_suffix(".backup")
+    shutil.copy(path, backup)
+```
+
+### Performance Optimization
+
+1. **Use RustworkX** for graphs >1000 nodes
+2. **Batch operations** when possible
+3. **Offload blocking I/O** to executor
+4. **Cache embeddings** (already in ChromaDB)
+5. **Limit graph traversal depth** (currently 1 hop)
+
+---
+
+## 🔍 Troubleshooting Guide
+
+### Issue: MCP Server Not Starting
+
+**Symptoms:**
+- IDE shows "Server failed to start"
+- No stderr output
+
+**Solutions:**
+1. Check Python path in `mcp.json`
+2. Verify `cwd` is absolute path
+3. Check `.env` file exists and is valid
+4. Test standalone: `python -m src.a_mem.main`
+5. Check logs: `tail -f data/graph_save.log`
+
+### Issue: Slow Retrieval Performance
+
+**Symptoms:**
+- `retrieve_memories` takes >5 seconds
+- Graph has >10,000 nodes
+
+**Solutions:**
+1. Switch to RustworkX: `GRAPH_BACKEND=rustworkx`
+2. Run enzymes to prune weak edges
+3. Increase `MIN_SIMILARITY_SCORE` to filter results
+4. Reduce `MAX_NEIGHBORS` for less graph traversal
+
+### Issue: Graph Data Lost After Restart
+
+**Symptoms:**
+- Notes disappear after server restart
+- Graph snapshot file empty
+
+**Solutions:**
+1. Check file permissions on `data/graph/`
+2. Verify no concurrent writes (check `graph.lock`)
+3. Enable FalkorDB for persistence: `GRAPH_BACKEND=falkordb`
+4. Check logs: `grep "ERROR" data/graph_save.log`
+
+### Issue: Research Agent Not Working
+
+**Symptoms:**
+- `research_and_store` returns no notes
+- Web search fails
+
+**Solutions:**
+1. Check environment:
+   - `RESEARCHER_ENABLED=true`
+   - `GOOGLE_API_KEY` set (or use DuckDuckGo fallback)
+   - `JINA_READER_ENABLED=true`
+2. Check server logs for `[RESEARCHER]` messages
+3. Test components:
+   ```bash
+   python tests/test_researcher_live.py
+   ```
+4. Verify network access (firewalls, proxies)
+
+### Issue: Memory Enzymes Causing Errors
+
+**Symptoms:**
+- Enzyme scheduler crashes
+- Event log shows `ENZYME_ERROR`
+
+**Solutions:**
+1. Check enzyme parameters (age, weight, threshold)
+2. Run enzymes manually with logging:
+   ```bash
+   python -c "from src.a_mem.utils.enzymes import *; run_memory_enzymes(...)"
+   ```
+3. Check for corrupted nodes:
+   ```bash
+   grep "CORRUPTED" data/events.jsonl
+   ```
+4. Reset if necessary (backup first!)
+
+### Issue: Embedding Dimension Mismatch
+
+**Symptoms:**
+- ChromaDB error: "Embedding dimension mismatch"
+- Different models produce different dimensions
+
+**Solutions:**
+1. Check model dimensions:
+   - `nomic-embed-text`: 768
+   - `text-embedding-3-small`: 1536
+2. Clear ChromaDB when switching models:
+   ```bash
+   rm -rf data/chroma/
+   ```
+3. See `docs/EMBEDDING_DIMENSIONS.md`
+
+---
+
+## 📚 Additional Resources
+
+### Documentation Files
+
+- **README.md** - User-facing documentation
+- **MCP_SERVER_SETUP.md** - MCP tool reference
+- **docs/MEMORY_ENZYMES_DETAILED.md** - Enzyme deep dive
+- **docs/RESEARCHER_AGENT_DETAILED.md** - Research agent guide
+- **docs/TEST_REPORT.md** - Test results
+- **docs/ARCHITECTURE_DIAGRAM.md** - Visual architecture (Mermaid)
+
+### Architecture Diagrams
+
+Located in `docs/*.svg`:
+- `a-mem-system-architecture.svg` - Overall system
+- `a-mem-storage-architecture.svg` - Storage layer
+- `a-mem-memory-enzymes.svg` - Enzyme workflow
+- `a-mem-mcp-tools.svg` - Tool overview
+- `a-mem-type-classification.svg` - Note type system
+
+### External Links
+
+- [Research Paper](https://arxiv.org/html/2502.12110v11) - Original A-Mem paper
+- [Original Repo](https://github.com/WujiangXu/A-mem-sys) - Authors' implementation
+- [MCP Documentation](https://modelcontextprotocol.io/) - Protocol spec
+
+---
+
+## 🎓 Learning Path for New Contributors
+
+### Week 1: Understand Architecture
+1. Read this file (CLAUDE.md)
+2. Read README.md
+3. Explore `src/a_mem/` structure
+4. Run tests: `python tests/test_a_mem.py`
+5. Read `src/a_mem/models/note.py`
+
+### Week 2: Core Components
+1. Study `src/a_mem/core/logic.py` (MemoryController)
+2. Study `src/a_mem/storage/engine.py` (Storage layer)
+3. Study `src/a_mem/utils/llm.py` (LLM integration)
+4. Run: `python -m src.a_mem.main` and test via Cursor
+
+### Week 3: Advanced Features
+1. Study `src/a_mem/utils/enzymes.py` (Memory maintenance)
+2. Study `src/a_mem/utils/researcher.py` (Web research)
+3. Study `src/a_mem/main.py` (MCP server)
+4. Run visualizer: `python tools/visualize_memory.py`
+
+### Week 4: Contribute
+1. Pick an issue or feature
+2. Write tests first
+3. Implement feature
+4. Run all tests
+5. Submit PR
+
+---
+
+## 📞 Getting Help
+
+**When asking for help, provide:**
+1. Error message (full traceback)
+2. Configuration (`.env` settings)
+3. Steps to reproduce
+4. Expected vs. actual behavior
+5. Relevant logs (`data/events.jsonl`, `data/graph_save.log`)
+
+**Debug checklist:**
+- [ ] Check `.env` file exists and is valid
+- [ ] Check Python version (3.9+)
+- [ ] Check dependencies: `pip install -r requirements.txt`
+- [ ] Check file permissions on `data/` directory
+- [ ] Check logs for errors
+- [ ] Test standalone: `python -m src.a_mem.main`
+
+---
+
+## 🔄 Changelog
+
+**v1.0 (December 1, 2025)**
+- Initial CLAUDE.md creation
+- Comprehensive architecture documentation
+- Development workflows and best practices
+- Troubleshooting guide
+- Learning path for new contributors
+
+---
+
+**End of CLAUDE.md**
+
+> This document is maintained by the community. When making significant architectural changes, please update this file accordingly.