diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..0782a46
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,28 @@
+# Cognitive Memory
+
+Markdown-based AI memory system — MCP server, CLI, decay scoring, episodic logging. stdlib-only (no pip dependencies).
+
+## Commands
+- Run CLI: `cd /mnt/NV2/Development/cognitive-memory && uv run python client.py <command>`
+- Wrapper: `claude-memory <command>` (installed at `~/.local/bin/claude-memory`)
+- MCP server: `python3 mcp_server.py` (stdio JSON-RPC, registered in `~/.claude.json`)
+
+## Architecture
+- `common.py` — constants, YAML parsing, decay math, helpers (everything imports from here)
+- `client.py` — `CognitiveMemoryClient` core API + CLI entrypoint (`if __name__`)
+- `cli.py` — argparse CLI, called from `client.py`'s `__main__` block
+- `edges.py`, `embeddings.py`, `analysis.py` — mixins composed into `CognitiveMemoryClient`
+- `mcp_server.py` — standalone MCP server wrapping `CognitiveMemoryClient`
+- Data lives at `~/.local/share/cognitive-memory/` (never in this repo)
+
+## Style
+- Flat module imports: `from common import ...`, `from client import ...` (no package prefix)
+- Mixin pattern: `EdgesMixin`, `EmbeddingsMixin`, `AnalysisMixin` composed via multiple inheritance
+- YAML frontmatter in memory files parsed manually (no PyYAML dependency)
+- All paths via `pathlib.Path`
+
+## IMPORTANT
+- Zero external dependencies — stdlib only. Ollama/OpenAI are optional HTTP calls.
+- `mcp_server.py` does `sys.path.insert(0, ...)` to find sibling modules — don't restructure without updating this
+- `feature.json` has stale `files` entries from pre-extraction — update when modifying file list
+- Skill layer at `~/.claude/skills/cognitive-memory/` (SKILL.md + SCHEMA.md) is separate — don't duplicate app code there