{"id":35771450,"url":"https://github.com/ilhan-monke/three-tier-ai-context","last_synced_at":"2026-01-07T04:18:42.200Z","repository":{"id":331094031,"uuid":"1125232562","full_name":"ilhan-monke/three-tier-ai-context","owner":"ilhan-monke","description":"Hierarchical session tracking system for AI assistants that reduces token usage by 60-80%","archived":false,"fork":false,"pushed_at":"2025-12-30T11:30:48.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-03T02:10:55.984Z","etag":null,"topics":["ai","ai-agents","ai-context","claude-code","developer-tools","documentation","productivity","session-tracking","templates","token-optimization"],"latest_commit_sha":null,"homepage":"https://ilhan-monke.github.io/three-tier-ai-context/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ilhan-monke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-30T11:12:52.000Z","updated_at":"2025-12-30T11:30:51.000Z","dependencies_parsed_at":"2026-01-03T12:04:38.914Z","dependency_job_id":null,"html_url":"https://github.com/ilhan-monke/three-tier-ai-context","commit_stats":null,"previous_names":["ilhan-monke/three-tier-ai-context"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ilhan-monke/three-tier-ai-context","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilhan-monke%2Fthree-tier-ai-context","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilhan-monke%2Fthree-tier-ai-context/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilhan-monke%2Fthree-tier-ai-context/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilhan-monke%2Fthree-tier-ai-context/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ilhan-monke","download_url":"https://codeload.github.com/ilhan-monke/three-tier-ai-context/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilhan-monke%2Fthree-tier-ai-context/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28232389,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-07T02:00:05.975Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","ai-context","claude-code","developer-tools","documentation","productivity","session-tracking","templates","token-optimization"],"created_at":"2026-01-07T04:18:39.264Z","updated_at":"2026-01-07T04:18:42.192Z","avatar_url":"https://github.com/ilhan-monke.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Three-Tier Documentation System\n\n**A hierarchical session tracking system for AI assistants that reduces token usage by 60-80%**\n\n## What Is This?\n\nWhen working with AI assistants on large repositories, loading context can consume 20-30k tokens per session. This system solves that problem with a smart three-tier hierarchical structure that lets you load only the context you need.\n\n## Quick Start\n\nSee [QUICKSTART_FOR_OTHERS.md](QUICKSTART_FOR_OTHERS.md) for a 5-minute setup guide.\n\n## Documentation\n\n- **[THREE_TIER_SYSTEM_GUIDE.md](THREE_TIER_SYSTEM_GUIDE.md)** - Complete system explanation and philosophy\n- **[QUICKSTART_FOR_OTHERS.md](QUICKSTART_FOR_OTHERS.md)** - Step-by-step setup guide\n- **[TEMPLATES/](TEMPLATES/)** - Ready-to-use template files\n\n## Token Savings\n\n**Before (flat structure):**\n- Load ALL documentation = 25,000 tokens every session\n\n**After (three-tier system):**\n- Working on specific project = 3,000 tokens (88% savings!)\n- Working on multiple projects = 5,000 tokens (80% savings!)\n- Working on vault structure = 10,000 tokens (60% savings!)\n\n## How It Works\n\nThe system organizes documentation into three tiers:\n\n### Tier 1: Vault/Root Level\n- Repository overview, git setup, cross-cutting work\n- **Read when:** Working on vault structure or multiple unrelated areas\n\n### Tier 2: Projects Overview\n- All projects summary, cross-project work\n- **Read when:** Working on multiple related projects\n\n### Tier 3: Individual Projects\n- Project-specific context and detailed history\n- **Read when:** Working on a single project (most common, biggest savings)\n\nContent automatically **propagates UP** from Tier 3 → Tier 2 → Tier 1, so every tier has complete context (detailed or summarized).\n\n## Workflow Diagrams\n\n### Starting a Session: Which Tier to Read?\n\n```\nWhat are you working on today?\n            ↓\n    ┌───────┴───────┬──────────────┬─────────────┐\n    │               │              │             │\nSingle Project  Multi-Project  Vault Work   Quick Check\n    │               │              │             │\n    ↓               ↓              ↓             ↓\nRead Tier 3     Read Tier 2    Read Tier 1   git log -5\n(~3-5k tokens) (~5-8k tokens) (~10k tokens)  (~1-3k tokens)\n    │               │              │             │\n    ↓               ↓              ↓             ↓\n88% savings     80% savings    60% savings   90%+ savings\n```\n\n**Example:**\n- Working on website project? → Read `projects/website/website-claude.md` (Tier 3)\n- Working on API + frontend? → Read `projects/projects-claude.md` (Tier 2)\n- Organizing documentation? → Read `docs/docs-claude.md` (Tier 1)\n- Just checking what changed? → Run `git log -5 --oneline --stat`\n\n### Ending a Session: Which Tiers to Update?\n\n```\n                    git diff --stat\n                          ↓\n                 Detect areas changed\n                          ↓\n        ┌─────────────────┼──────────────────┐\n        │                 │                  │\n   Single Project    Multi-Project       Vault-Level\n      Work              Work                Work\n        │                 │                  │\n        ↓                 ↓                  ↓\n    Update T3         Update T3s         Update T1\n    Update T2         Update T2           (only)\n    Update T1         Update T1\n        │                 │                  │\n        └─────────────────┼──────────────────┘\n                          ↓\n          Commit all modified session files\n                          ↓\n                   Push to GitHub\n```\n\n**Example:**\n- Changed `projects/website/src/index.html`? → Update Tier 3 (website) + Tier 2 + Tier 1\n- Changed files in both `api/` and `frontend/`? → Update both Tier 3s + Tier 2 + Tier 1\n- Changed `README.md` and `docs/`? → Update Tier 1 only\n\n**The agent handles this automatically!** Just run `@agents/close_and_commit_GIT.md`\n\n## Features\n\n- ✅ **60-80% token reduction** through smart context loading\n- ✅ **Automatic tier detection** via git diff analysis\n- ✅ **Content propagation** from specific to general\n- ✅ **Session management agent** that handles everything automatically\n- ✅ **Descriptive file naming** for easy identification\n- ✅ **Complete templates** ready to copy and customize\n- ✅ **Language-agnostic** - works with any codebase\n- ✅ **AI-agnostic** - works with Claude, Cursor, Windsurf, etc.\n\n## Setup\n\n```bash\n# Copy templates to your repository\ncp -r TEMPLATES /path/to/your-repo/\n\n# Run automated setup\ncd /path/to/your-repo\nbash TEMPLATES/setup-three-tier.sh\n\n# Customize the templates and start using!\n```\n\nSee [QUICKSTART_FOR_OTHERS.md](QUICKSTART_FOR_OTHERS.md) for detailed instructions.\n\n## Who Is This For?\n\n- Developers with large repositories and multiple projects\n- Teams using AI assistants (Claude Code, Cursor, etc.)\n- Anyone wanting to reduce AI token costs\n- Projects needing organized session tracking\n\n## Philosophy\n\n**\"Load only what you need\"**\n\nMost work is focused on ONE area. Reading everything is wasteful. Context should be available at appropriate granularity. Smart architecture upfront pays dividends in reduced token costs.\n\n## Based On\n\nThis system builds upon:\n- NetworkChuck's AI terminal workflow patterns (session-summary.md, claude.md)\n- Real-world usage and iteration\n- Token efficiency best practices\n\n## Innovation\n\nWhile session tracking patterns exist, the three-tier hierarchical approach with automatic propagation and smart tier detection is a novel solution specifically designed for token efficiency at scale.\n\n## License\n\nMIT License - Feel free to use, modify, and share!\n\n## Contributing\n\nFound this useful? Have improvements? Issues and pull requests welcome!\n\n---\n\n**Quick Reference:**\n\n| Work Type | Files to Read | Token Cost | Savings |\n|-----------|---------------|------------|---------|\n| Specific project | Tier 3 project files | ~3-5k | 88% |\n| Multiple projects | Tier 2 files | ~5-8k | 80% |\n| Vault structure | Tier 1 files | ~10k | 60% |\n| Quick context | `git log -5 --oneline --stat` | ~1-3k | 90%+ |\n\n**Start saving tokens today!** 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filhan-monke%2Fthree-tier-ai-context","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filhan-monke%2Fthree-tier-ai-context","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filhan-monke%2Fthree-tier-ai-context/lists"}