swf-testbed/docs/ai-memory.md

0001 # AI Memory - Cross-Session Dialogue Persistence
0002
0003 **Status: Experimental**
0004
0005 AI memory enables Claude Code to recall recent conversations across sessions.
0006 When enabled, user prompts and assistant responses are recorded via hooks and
0007 loaded into new sessions for continuity.
0008
0009 ## How It Works
0010
0011 Claude Code [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) run
0012 at session boundaries:
0013
0014 - **SessionStart**: Loads recent dialogue turns into the new session context
0015 - **UserPromptSubmit**: Records each user prompt
0016 - **Stop**: Records the assistant's last response
0017
0018 The hooks call the [tjai](https://etaverse.com/tjai/) REST API (`/api/dialog`)
0019 to store and retrieve dialogue.
0020
0021 ## Setup
0022
0023 ### 1. Environment variables
0024
0025 Add to `~/.env` (or `~/.bashrc`):
0026
0027 ```bash
0028 export TJAI_API_KEY="your-api-key"
0029 export TJAI_API_URL="https://etaverse.com/tjai"   # default if omitted
0030 export TJAI_DIALOG_TURNS=20                        # number of turns to load; 0 = disabled
0031 ```
0032
0033 ### 2. Install hook scripts
0034
0035 Copy the hooks from `tjrepo/computers/common/claude-hooks/` to `~/.claude/hooks/`:
0036
0037 ```bash
0038 mkdir -p ~/.claude/hooks
0039 cp /data/wenauseic/github/tjrepo/computers/common/claude-hooks/*.py ~/.claude/hooks/
0040 ```
0041
0042 ### 3. Configure Claude Code settings
0043
0044 Add hooks to your **global** `~/.claude/settings.json` (not project-level, so
0045 they apply across all projects):
0046
0047 ```json
0048 {
0049   "hooks": {
0050     "SessionStart": [
0051       {
0052         "hooks": [
0053           {
0054             "type": "command",
0055             "command": "python3 ~/.claude/hooks/load.py",
0056             "timeout": 10
0057           }
0058         ]
0059       }
0060     ],
0061     "UserPromptSubmit": [
0062       {
0063         "hooks": [
0064           {
0065             "type": "command",
0066             "command": "python3 ~/.claude/hooks/record.py",
0067             "timeout": 10,
0068             "async": true
0069           }
0070         ]
0071       }
0072     ],
0073     "Stop": [
0074       {
0075         "hooks": [
0076           {
0077             "type": "command",
0078             "command": "python3 ~/.claude/hooks/record.py",
0079             "timeout": 10,
0080             "async": true
0081           }
0082         ]
0083       }
0084     ]
0085   }
0086 }
0087 ```
0088
0089 A complete reference settings file is at
0090 `tjrepo/computers/common/claude-settings.json`.
0091
0092 ## Disabling
0093
0094 Set `TJAI_DIALOG_TURNS=0` or unset it. The hooks exit immediately when
0095 the variable is absent or zero.
0096
0097 ## Files
0098
0099 | Location | Purpose |
0100 |----------|---------|
0101 | `~/.claude/hooks/load.py` | SessionStart hook - loads SYSPROMPT.md + recent dialogue |
0102 | `~/.claude/hooks/record.py` | UserPromptSubmit/Stop hook - records exchanges |
0103 | `~/.claude/hooks/SYSPROMPT.md` | Optional system prompt injected at session start |
0104 | `tjrepo/computers/common/claude-hooks/` | Canonical source for hook scripts |
0105 | `tjrepo/computers/common/claude-settings.json` | Reference settings with hooks configured |
0106
0107 ## Troubleshooting
0108
0109 - **No dialogue loading?** Check `TJAI_DIALOG_TURNS` is set and > 0,
0110   and `TJAI_API_KEY` is set. Restart the session after changing env vars.
0111 - **Hook errors?** Hooks print to stderr. Run manually to test:
0112   `echo '{"hook_event_name":"UserPromptSubmit","prompt":"test"}' | python3 ~/.claude/hooks/record.py`