wehub-resource-sync
101 lines
4.4 KiB
Markdown
101 lines
4.4 KiB
Markdown
# Session Memory
|
|
|
|
ArcKit includes automated session capture that records what happened during each Claude Code session. This complements Claude Code's built-in auto-memory by tracking the *actual work done* (git commits, artifact types) rather than relying on what Claude decides to remember.
|
|
|
|
## How It Works
|
|
|
|
```text
|
|
Session N ends
|
|
└── session-learner.mjs (Stop hook) analyses recent git commits
|
|
└── appends summary to .arckit/memory/sessions.md
|
|
|
|
Session N+1 starts
|
|
└── arckit-session.mjs (SessionStart hook) reads sessions.md
|
|
└── surfaces last 3 sessions as context
|
|
```
|
|
|
|
The Stop hook fires automatically when a session ends. No configuration needed beyond installing the ArcKit plugin.
|
|
|
|
## What Gets Captured
|
|
|
|
Each session entry includes:
|
|
|
|
- **Session classification** — compliance, governance, research, procurement, architecture, planning, discovery, operations, or general (auto-detected from artifact types)
|
|
- **Commit count and files changed** — quantitative measure of session activity
|
|
- **Artifact types** — which ArcKit document types (ADR, HLDR, WARD, etc.) were created or modified
|
|
- **Commit summaries** — up to 8 commit messages for context
|
|
|
|
## Session Classification
|
|
|
|
Sessions are classified by the highest-priority category of artifacts touched:
|
|
|
|
| Priority | Classification | Triggered by category |
|
|
|---|---|---|
|
|
| 1 | `compliance` | Compliance artifacts (TCOP, SECD, DPIA, JSP936, SVCASS, etc.) |
|
|
| 2 | `governance` | Governance artifacts (RISK, TRAC, PRIN-COMP, CONF, etc.) |
|
|
| 3 | `research` | Cloud research artifacts (AWRS, AZRS, GCRS) |
|
|
| 4 | `procurement` | Procurement artifacts (SOW, EVAL, DOS, GCLD, VEND, etc.) |
|
|
| 5 | `architecture` | Architecture artifacts (ADR, HLDR, DLDR, DIAG, WARD, etc.) |
|
|
| 6 | `planning` | Planning artifacts (SOBC, PLAN, ROAD, STRAT, BKLG) |
|
|
| 7 | `discovery` | Discovery artifacts (REQ, STKE, RSCH, DSCT) |
|
|
| 8 | `operations` | Operations artifacts (SNOW, DEVOPS, MLOPS, FINOPS, OPS) |
|
|
| 9 | `general` | No ARC artifacts or Other category only |
|
|
|
|
## Timestamp Tracking
|
|
|
|
The session-learner uses timestamp-based tracking to capture exactly the commits from each session:
|
|
|
|
- Timestamp stored in `.arckit/memory/.last-session`
|
|
- Each session captures commits since the previous session ended
|
|
- First run uses `--since=4 hours ago` as a bootstrap
|
|
- No overlap between sessions, no missed commits
|
|
|
|
## Storage
|
|
|
|
Session history is stored in `.arckit/memory/sessions.md` — a rolling log of the last 30 sessions. This file is committed to git by default for team visibility.
|
|
|
|
### Example Entry
|
|
|
|
```markdown
|
|
### 2026-03-08 14:30 — governance
|
|
|
|
- **Commits:** 4 | **Files changed:** 7
|
|
- **Artifacts:**
|
|
- [001] Governance: Risk Register | Architecture: Architecture Decision Records
|
|
- [002] Compliance: Secure by Design
|
|
- **Summary:**
|
|
- feat: add SECD assessment for cloud migration
|
|
- docs: update ADR-003 with security review outcome
|
|
- fix: correct risk rating in RISK register
|
|
- chore: update traceability matrix
|
|
```
|
|
|
|
Artifacts are grouped by project number (e.g., `[001]`) and organized by category, making it easy to see which projects were active and what type of work was done.
|
|
|
|
## Relationship to Auto-Memory
|
|
|
|
| Feature | Claude Auto-Memory | Session Learner |
|
|
|---|---|---|
|
|
| **What it captures** | What Claude decides is important | What actually happened (git commits) |
|
|
| **Trigger** | Automatic (Claude's judgement) | Deterministic (Stop hook on every session) |
|
|
| **Storage** | `~/.claude/projects/<project>/memory/` (machine-local) | `.arckit/memory/sessions.md` (in-repo) |
|
|
| **Team sharing** | Not shareable | Committed to git |
|
|
| **Content** | Freeform insights, preferences | Structured session summaries |
|
|
|
|
The two systems are complementary, not competing. Auto-memory captures *insights*; session-learner captures *activity*.
|
|
|
|
## Troubleshooting
|
|
|
|
**No sessions.md created after ending a session:**
|
|
|
|
- Check that `.arckit/` directory exists in your project root
|
|
- Verify there were git commits since the last recorded session (or within 4 hours on first run)
|
|
- Check hook registration: `hooks.json` should include a `Stop` event
|
|
|
|
**Session classification seems wrong:**
|
|
|
|
- Classification is based on artifact type codes in filenames (e.g., `ARC-001-SECD-v1.md`)
|
|
- Non-ARC files don't contribute to classification
|
|
- Sessions with no detected ARC artifacts default to `general`
|
|
- When multiple categories are present, the highest-priority one wins (compliance > governance > research > ...)
|