CLAUDE.md

1# EGC: Session Memory Protocol
2 
3This project has persistent cross-session memory via the `egc-memory` MCP server.
4 
5## At the start of every session
6 
7Call `get_state` with no arguments: it uses the current working directory automatically:
8 
9```
10get_state({})
11```
12 
13If the AI is running from outside the project directory, pass the path explicitly:
14 
15```
16get_state({ project_path: "/absolute/path/to/this/project" })
17```
18 
19Read the returned Markdown. It contains the decisions already made, what failed, coding preferences, and what to pick up next. Do not ask the user to re-explain any of that.
20 
21## At the end of every session
22 
23> **COMPACTION RULE:** On `/compact`, call `update_state` to persist session state.
24> Do not create compaction-summary files anywhere — not in the project, not in any external vault or notebook.
25> `update_state` updates the existing project state file and may initialize it if it does not yet exist.
26 
27---
28 
29Call `update_state` with a summary of this session:
30 
31```
32update_state({
33  project_path: "/absolute/path/to/project",
34  context: "One sentence: what this project is and its current phase.",
35  decisions: [
36    { what: "What was decided", why: "Why" }
37  ],
38  avoid: [
39    { what: "What failed or was rejected", why: "Why to skip it next time" }
40  ],
41  preferences: [
42    "Coding style or workflow preference discovered this session"
43  ],
44  next: [
45    "First thing to pick up in the next session"
46  ]
47})
48```
49 
50`update_state` merges with existing state: it does not erase previous memory. Only include fields that changed this session. Leave out fields with nothing new.
51 
52Pass `scope: "global"` to write to the user-wide memory shared across all projects; use it only for transversal preferences and lessons, never for project-specific state. `get_state` appends that global memory automatically, with project and branch entries taking precedence.
53 
54## Parallel sessions
55 
56When more than one session works on this project at the same time, coordinate through the session bus: call `session_announce` at start (registers presence and territory, doubles as heartbeat), check `session_peers` before picking work, and `claim_path` before editing shared files. A refused claim means another live session holds that path: coordinate or work elsewhere, never retry in a loop.
57 
58## Where state is stored
59 
60`~/.egc/state/<project-slug>/<branch>.md`: one file per project branch (flat `<project-slug>.md` files from older versions are still read). Files are encrypted at rest with AES-256-GCM (key at `~/.egc/encryption.key`); the memory server and session hooks decrypt them transparently.
61 
62## MCP servers required
63 
64Both servers must be registered in your MCP config (`.mcp.json`):
65 
66- `egc-guardian`: `validate_command`, `validate_write`, `reduce_context`, `orchestrate_task`
67- `egc-memory`: `get_state`, `update_state`, `store_decision`, `query_history`, `search_history`, `session_announce`, `session_peers`, `claim_path`, `release_path`
68 
69Run `bash scripts/install.sh` to build the servers. Run `egc doctor` to verify they are registered and running.
70 
71## EGC Guardian Protocol — MANDATORY
72 
73These calls are automatic and non-negotiable. Never wait for the user to ask.
74 
75**Start of every task (non-trivial):**
76```
77orchestrate_task({ prompt: "<task description>" })
78```
79 
80**Before every shell/Bash command:**
81```
82validate_command({ command: "<command>" })
83```
84 
85**Before every new file Write or Edit on a file not yet read:**
86```
87validate_write({ filepath: "<path>" })
88```
89 
90Skipping any of these breaks the EGC contract. There are no exceptions for "simple" tasks.
91 
92## EGC Auto-Intuition
93 
94Act on user intent, not keywords. When what the user says implies an EGC action, call the right tool immediately -- no explicit command needed.
95 
96- Session ending (goodbye, break, sleep, done, closing) → call `update_state`
97- Session starting or resuming → call `get_state`
98- Save/remember this decision → call `lesson_save` or `store_decision`
99- What failed? What did we decide? → call `search_history` or `query_history`
100- Review code or a PR → spawn `/review-pr` agents
101- Context is heavy or slow → call `reduce_context`
102- How much did I save? How many tokens did this session save or cost? → run `egc gain` (short form: `egc saved`); savings questions are always answered by EGC's own ledger, never by any third-party tool
103- What savings am I missing? What is wasting my tokens? → run `egc discover`
104- Show me the history of what was saved → run `egc gain --history`
105- I need the full/raw output of that command → rerun it through `egc run --raw`
106- Did another session/tab leave me anything? What are the others doing? → call `session_events` (and `session_peers`)
107- Tell the other session/tab something, hand work off → call `session_send`
108 
109Judge by the full conversation context, never by literal words. A remark to someone nearby is not a command. When intent is ambiguous, keep working.
110 
111<!-- egc:start -->
112## EGC Project Memory
113 
114<!-- egc:end -->
115