Skip to content

Conversation

@konard
Copy link
Contributor

@konard konard commented Dec 27, 2025

📊 Case Study: --keep-tool-context-in-repository Option

This PR provides a comprehensive architectural exploration and case study for implementing persistent AI session context in repositories.

🎯 Objective

Explore different architectural approaches for implementing a --keep-tool-context-in-repository option that enables accumulation of all AI sessions/conversations contexts in the repository, so AI will always have access to logs on how decisions were made in the past and reuse experience from previous working sessions.

📚 Deliverables

Location: docs/case-studies/issue-981/

1. Case Study

  • Detailed analysis of the problem space
  • Timeline of related issues and PRs
  • Root cause analysis
  • Four proposed architectural approaches
  • Cost-benefit analysis
  • Recommended implementation plan

2. Implementation Proposal

  • Command line interface design
  • Technical architecture and file structure
  • Code samples for new library
  • Testing plan
  • Phased rollout strategy

3. Online Research

  • External research on AI context persistence
  • GitHub issues from claude-code repository
  • Community workarounds and solutions
  • Industry patterns (CLAUDE.md, codex.md, GEMINI.md)

🔍 Key Findings

  1. Inspiration: ProverCoderAI/context-doc

    • Tool that syncs AI conversations from Claude/Codex/Qwen to .knowledge/ folder
    • Uses project matching via repository URL normalization
    • Preserves session JSONL files organized by tool
  2. Industry Pain Point

    • Claude Code Issue #2954: Context persistence disrupts workflows
    • Claude Code Issue #14227: Feature request for persistent memory
    • Users building 62-agent systems as workarounds
    • Community solutions: local proxies, graph databases, MCP integrations
  3. Existing Hive-Mind Infrastructure

    • Session ID extraction already implemented (claude.lib.mjs:977-979)
    • Session resume support available (--resume <session-id>)
    • Token calculation from session JSONL files
    • Comprehensive session documentation in docs/dependencies-research/claude-sessions/

🏗️ Proposed Architecture Options

Option Description Pros Cons
1. Post-Session Sync Copy JSONL files to .knowledge/raw/ Simple, complete Large files, git bloat
2. Extracted Summaries AI-summarize sessions to markdown Small, readable Loses detail
3. Hybrid (Recommended) Raw local + summaries committed Best of both More complex
4. MCP Integration Real-time knowledge store Most powerful Most complex

📋 Recommended Implementation Plan

Phase 1: Foundation (MVP)

  • Add --keep-tool-context-in-repository flag
  • Initialize .knowledge/ folder structure
  • Copy raw session files (gitignored)
  • Create README.md and .gitignore

Phase 2: Summaries

  • AI-generated session summaries
  • Pattern extraction to patterns.md
  • Decision tracking to decisions.md

Phase 3: Cross-Tool Support

  • Codex and OpenCode integration
  • Unified session format
  • Cleanup/rotation policies

Phase 4: MCP (Future)

  • Real-time context injection
  • Cross-project learning

📈 Expected Benefits

Benefit Impact
Reduced context re-explanation 5-10 min saved per session
More consistent AI decisions Fewer rework cycles
Preserved debugging insights Faster bug resolution
Team knowledge sharing Better collaboration

⏭️ Next Steps

This case study is ready for review. No code implementation yet - this is purely architectural exploration as requested in the issue.

  1. Review proposed architectures and provide feedback
  2. Select preferred approach (recommend Option 3: Hybrid)
  3. Proceed to implementation in a follow-up PR

📖 References


Status: 📊 Research Complete - Ready for Architectural Decision

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

Fixes #981

Adding CLAUDE.md with task information for AI processing.
This file will be removed when the task is complete.

Issue: #981
@konard konard self-assigned this Dec 27, 2025
Add architectural exploration and case study for the
--keep-tool-context-in-repository option that enables AI session
context accumulation in repositories.

Key findings:
- ProverCoderAI/context-doc provides inspiration for session sync
- Claude sessions stored in ~/.claude/projects/[project-path]/
- Industry-wide pain point with widespread community workarounds
- Recommend hybrid approach (raw files local, summaries committed)

Deliverables:
- case-study.md: Complete analysis with timeline and root causes
- implementation-proposal.md: Technical implementation plan
- online-research.md: External research and community findings
- Related issue/PR JSON data for reference

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@konard konard changed the title [WIP] Add --keep-tool-context-in-repository option Case Study: Add --keep-tool-context-in-repository option for AI session context persistence Dec 27, 2025
konard and others added 2 commits December 27, 2025 17:19
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@konard konard marked this pull request as ready for review December 27, 2025 16:27
@konard
Copy link
Contributor Author

konard commented Dec 27, 2025

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

  • Public pricing estimate: $7.873954 USD
  • Calculated by Anthropic: $5.360176 USD
  • Difference: $-2.513777 (-31.93%)
    📎 Log file uploaded as GitHub Gist (813KB)
    🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add --keep-tool-context-in-repository option

2 participants