claude-memory/graph/problems/cognitive-memory-clientpy-at-3260-lines-needs-modular-refact-8d3654.md

id	type	title	tags	importance	confidence	created	updated
8d365483-701f-49fe-a55e-4d524ae2eff3	problem	cognitive-memory client.py at 3348 lines needs modular refactor	cognitive-memory refactoring architecture tech-debt	0.7	0.9	2026-02-19T20:57:01.898902+00:00	2026-02-28T00:00:00+00:00

client.py has grown to 3348 lines with 66 methods (was 3260/47 on 2026-02-19). Breakdown by concern with accurate line counts:

• common.py (~548 lines): Constants, imports, YAML/frontmatter parsing, slugify, decay calc, embedding helpers, cosine similarity, edge filename/frontmatter helpers
• client.py (~1008 lines): CognitiveMemoryClient class — init, internal helpers (_ensure_dirs, _load/_save index/state, _resolve paths, _git_commit, _update_index_entry), store, recall, get, search, update, delete, related, stats, recent, episode, reindex, pin
• edges.py (~274 lines): relate, edge_get, edge_search, edge_update, edge_delete + edge index helpers (_update_edge_index, _remove_edge_index, _scan_for_edge, _resolve_edge_path)
• embeddings.py (~208 lines): _get_embedding_provider, _embed_texts_with_fallback, embed, semantic_recall
• analysis.py (~839 lines): decay, core (CORE.md gen), tags_list/related/suggest, reflect, merge, reflection_summary — biggest chunk
• cli.py (~471 lines): argparse parser + dispatch + main()

Approach: mixin classes. Each module defines a Mixin class; CognitiveMemoryClient inherits from all mixins. This preserves self access and keeps the public API identical.

Refactor considerations:

• MCP server imports from client import CognitiveMemoryClient — needs re-export or updated import
• CLI wrapper at /home/cal/.local/bin/claude-memory uses exec uv run python client.py — cli.py must be runnable
• Systemd services (daily/weekly timers) depend on the wrapper — must test after
• mcp_server.py also imports _load_memory_config, MEMORY_DIR from client — move to common.py
• 4 module-level helper functions are used across concerns — belong in common.py

Priority: active. Line count growing, 66 methods in one class makes navigation painful.