tractorjuice--arckit-gemini/docs/guides/session-memory.md

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

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

### 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 > ...)