cognitive-memory/CLAUDE.md

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