Deep Dive

Filesystem Architecture

Why JSON instead of DB, how workspaces are isolated, and the storage format in detail.

01
Workspace Isolation

Each project gets its own folder under ~/.context-memory/. No project sees another's data. Name is sanitized: special chars removed, lowercase.

# get_workspace() in cm_core.py
safe_name = re.sub(r'[^\w\-.]]', '_', project.lower())

"My Project!" → my_project_
02
Index vs. Node Files

The index (index.json) is a flat key-value store: node ID → metadata. Actual content lives as Markdown in nodes/. This way the index can be searched quickly without reading all files.

index.json ← fast metadata access
{"arch-001": {"title":..., "tags":..., "confidence":...}}

nodes/arch-001.md ← full content, read on demand
03
History & Concurrent Access

history.json logs every action. Max 500 entries, FIFO. Concurrent access: last-write-wins. No locking, but documented in log.

# Audit Trail
[{"action": "add", "node_id": "dec-001"},
 {"action": "ingest", "node_id": "arch-001"},
 ...] ← max 500