Keep project context across Claude Code sessions
Keep project context across Claude Code sessions
By Mike Schreiber
The title describes a frustrating feeling, not literal memory loss. Claude Code supports persistent instructions in CLAUDE.md, which it reads at session start, and editable auto memory. The useful question is how to make the next session start with an accurate account of the work, rather than another explanation of it. Claude Code memory documentation
Consider a hypothetical authentication project. On Tuesday, you approve database-backed sessions, reject a caching change, and leave a logout test unfinished. On Wednesday, you want the next session to distinguish those choices from suggestions that never became decisions.
The solution is not to preserve every sentence. It is to maintain a compact, reviewable handoff: the goal, current state, accepted decisions and rationale, unresolved problems, and next action.
1. Separate durable instructions from current work
Start by sorting your project context into two buckets.
Durable instructions describe how to work: build commands, coding conventions, and rules that apply across sessions. Claude Code’s documentation recommends keeping these session-wide facts in CLAUDE.md, moving multistep procedures into skills and narrowly scoped instructions into path-scoped rules. Claude Code memory documentation
Current work describes where to resume: what changed, what remains uncertain, which test needs attention, and what a person approved. Maintain this as a handoff rather than mixing it into every permanent instruction.
For the hypothetical authentication project:
- Durable instruction: “Run the authentication test suite before proposing an auth change.”
- Current state: “Logout implementation changed; the expiry test still needs investigation.”
- Human decision: “Keep sessions in the database because immediate revocation is required.”
- Next action: “Reproduce the expiry failure before changing storage behavior.”
You can start with a manually maintained note. Before introducing automation, check whether this separation makes a fresh-session prompt clearer.
2. Label decisions, observations, and proposals
A useful record needs more than a summary. Give each statement a clear status.
Human decisions record an authorized choice and its rationale. In the hypothetical example, database-backed sessions are a decision only after the responsible person approves that constraint.
Observed work records evidence: a commit exists, a file changed, or a particular test passed. An observation should not imply more than its evidence supports. Passing one logout test does not establish that authentication is production-ready.
Proposed notes describe interpretations awaiting review. “Consider caching session lookups” belongs here until someone evaluates it.
Hark’s Standard trust level requires review of agent proposals, while repository facts backed by a commit, pull request, or release are accepted as observed. Decisions are never automatically approved at any trust level. Other proposal types can be auto-approved under higher trust settings, so review the project’s setting before relying on its record. Hark agent guidance
Use this distinction even without Hark. Ask the agent to label uncertain conclusions explicitly, then review them before treating them as instructions.
3. Establish a starting brief
Write a starting brief that answers:
- What outcome is the project pursuing?
- Where did work stop?
- Which accepted decisions still apply, and why?
- What failed or remains unknown?
- What should happen next?
Keep the next action executable. “Finish auth” is vague. “Reproduce the expired-session logout failure and report the failing assertion before editing” gives the incoming session a bounded task.
For an existing repository, Hark documents a setup flow using propose_venture_from_project to propose project information, current build state, and visible decisions. The agent then asks for a constraint or decision not visible in the code and records it with add_journal_entry. Review inferred rationale rather than assuming the repository proves why a choice was made. Hark repository setup
A hypothetical hidden constraint might be: “Support staff must be able to revoke access immediately.” That context explains a storage choice more clearly than the implementation alone.
4. Connect Claude Code and verify the brief
If you want the session workflow integrated, the early-access Hark mod requires Claude Code 2.1.287 or newer. Install it from the repository using these commands inside Claude Code. Hark Claude Code connection
/plugin marketplace add Hark-Studio/hark-mod
/plugin install hark-memory@hark
Next, open Connections → Access keys → Claude Code preset in Hark and create a pairing code. Have the agent exchange it and store the returned access key in the plugin’s sensitive configuration, never in chat. Open that configuration with the following command. Hark mod setup
/plugin configure hark-memory@hark
Link the repository using your actual project code. Here, V-012 is only an example. Then start Claude Code in the project and run /hark brief. Without a project file or key, the mod stays idle and sends nothing. Hark mod setup
mkdir -p .hark && echo V-012 > .hark/project
Read the returned brief before authorizing edits. Check the project identity, accepted constraint, unresolved issue, and next action. A successful connection is not the same as an accurate handoff.
5. Keep the record aligned during work
The Hark mod fetches the compact project brief at session start and adds it to the first message. After compaction, it restores agreed decisions, non-goals, blockers, and the next action. Hark mod behavior
Its decision guard presents the decision and rationale before edits to files covered by an agreed decision or non-goal, allowing you to choose Allow or Stop. The check runs locally, and information about the edit is not sent. Treat this as a review checkpoint, not proof that every possible architectural conflict will be detected. Hark decision guard
In the hypothetical project, give the session-storage decision a relevant file scope. If a proposed change introduces caching, pause to ask whether it preserves immediate revocation. Do not silently replace the original rationale with the agent’s interpretation.
Hark’s agent guidance requires explicit user confirmation before supersede_decision replaces an earlier decision. That keeps a changed human choice distinct from an implementation observation. Hark agent guidance
6. Review the handoff, then test a fresh session
When a changed session ends, the mod sends a short summary covering file paths, commits, test results, and Claude’s closing notes, and Hark drafts a handoff for review. Sessions with no changes write no handoff. Hark handoff behavior
Review the draft against the actual work:
- Does “implemented” mean edited, tested, or approved?
- Are failures and untested paths visible?
- Are suggestions still labeled as proposals?
- Can someone execute the next action without guessing?
Then start a fresh session and ask it to state the accepted constraint before making changes. Hark’s documented verification flow uses get_agent_brief in a fresh session or another connected client to retrieve a recorded constraint. This tests access to project context, not transfer of chat history. Hark handoff verification
Troubleshooting and boundaries
No brief appears: Check the sensitive key setting, the .hark/project or .hark project file, and the required Claude Code version. Hark mod troubleshooting
The guard interrupts unrelated edits: Narrow decisions to the relevant area or path, such as src/auth/** in this hypothetical project. Hark recommends decision scopes when the guard asks too often. Hark mod troubleshooting
No handoff appears: The mod documentation identifies network trouble at exit as a usual cause and describes a fallback draft from repository activity after 45 minutes idle. Inspect that draft for missing rationale; repository activity cannot substitute for an unrecorded human choice. Hark mod troubleshooting
Sensitive work is involved: The mod does not send file contents, diffs, prompts, transcripts, tool output, or environment variables. It does send handoff metadata and closing notes. Notes cleaning is best effort, and secrets written in prose could be sent. Keep secrets out of summaries. Hark privacy and trust
FAQs
Does Claude Code actually forget everything?
No. It reads persistent CLAUDE.md instructions and supports auto memory. Use /memory to browse and edit memory files. Claude Code memory documentation
Can this work without installing the mod?
Yes. Start with a reviewed handoff note. Hark also documents a Claude Code MCP connection without the mod. Hark Claude Code connection
Does automation approve architectural decisions?
Not in Hark: decisions are never automatically approved, regardless of trust level. Keep human approval separate from observed work and proposed notes. Hark approval boundaries
Sources
