🚀 BREAKTHROUGH v1.0.4 - Detection-Hourglass-System (DHS) WORKING! 🎉 Revolutionary auto-detection achieved! Complete pipeline from detection to AI processing to file storage - FULLY FUNCTIONAL!
🔥 BREAKTHROUGH ACHIEVED:
- 🕐 Detection-Hourglass-System - ✅ WORKING - Auto-detects conversation boundaries
- 🎯 Universal AI compatibility - ✅ TESTED - Works with Claude, ChatGPT, Copilot, Cursor
- ⚡ Dynamic chunk processing - ✅ LIVE - Natural conversation segments (5-6ms processing)
- 💰 Zero-cost operation - ✅ VERIFIED - Logic agents run locally, no API calls
- 🤖 Auto-trigger detection - ✅ FUNCTIONAL - AI code execution = automatic user input detection
- 🔗 Complete pipeline - ✅ CONNECTED - Real conversation data flows to agents and files
- 32 comprehensive templates for all major tech stacks
AI Memory System with Zero-Cost Logic Agent Orchestrator
Create a .ai/ knowledge base that preserves your conversation context using specialized logic agents. Zero API costs. Lightning fast processing. Works with all major AI assistants.
CRITICAL: Before working on this project, read the .ai/ knowledge base:
.ai/project-overview.md- Project context and conventions.ai/conversation-log.md- Key decisions from previous chats.ai/technical-decisions.md- Why we chose X over Y
Why? This preserves institutional knowledge so you have full context immediately.
See .ai-instructions file for detailed instructions.
When working with AI coding assistants (ChatGPT, Claude, Copilot, Cursor, Augment, Warp, etc.), every new chat session loses all context. You have to re-explain your project architecture, technical decisions, why you chose X over Y, what you accomplished in previous sessions, and known issues. This wastes significant time in every chat session.
Unlike other AI context tools that focus on project planning and rules, create-ai-chat-context focuses on preserving conversation history and technical decisions across sessions. It works with ALL AI assistants and maintains institutional knowledge through files like conversation-log.md, technical-decisions.md, and known-issues.md.
create-ai-chat-context creates a .ai/ knowledge base in your project that AI assistants read at the start of each chat. Plus optional .aicf/ format for 85% token reduction. Result: AI gets full context immediately. No more re-explaining.
The tool creates 7 essential documentation files in your project:
| File | Purpose |
|---|---|
| conversation-log.md | Chat history and key decisions |
| technical-decisions.md | Why you chose X over Y |
| next-steps.md | Current priorities and tasks |
| project-overview.md | Project context for AI assistants |
| design-system.md | Design patterns and conventions |
| code-style.md | Coding standards and guidelines |
| README.md | Overview of the knowledge base |
Simple, focused, and effective. No complex formats or token optimization needed.
Mind-blowing coverage: We support virtually every major programming language, framework, and development category!
- nextjs - Next.js, React, TypeScript projects
- react - React, Create React App, Vite projects
- vue - Vue.js, Nuxt.js, Vite projects
- angular - Angular projects with TypeScript
- node - Node.js backend projects, Express, NestJS
- python - General Python projects
- django - Django web framework projects
- fastapi - FastAPI backend projects
- flask - Flask web framework projects
- rust - Rust systems programming projects
- go - Go backend and systems projects
- cpp - C++ systems and application projects
- java - Java projects, Spring Boot, Maven/Gradle
- spring - Spring Boot, Spring Framework projects
- kotlin - Kotlin projects, Android, multiplatform
- csharp - C# .NET projects
- dotnet - .NET Core, ASP.NET Core projects
- php - PHP projects, Laravel, Symfony
- laravel - Laravel PHP framework projects
- ruby - Ruby projects, Ruby on Rails
- rails - Ruby on Rails web framework projects
- mobile - React Native, Flutter, Swift, Kotlin
- fullstack - Full-stack projects with frontend + backend
- api - Generic backend API projects
- database - Database design, migrations, stored procedures
- devops - Docker, Kubernetes, CI/CD, Infrastructure
- terraform - Infrastructure as Code with Terraform
- ai_ml - Machine Learning, Deep Learning, Data Science
- blockchain - Smart contracts, DApps, cryptocurrency
- gamedev - Unity, Unreal, indie games, mobile games
Each template includes:
- Language-specific project structure
- Framework conventions and best practices
- Common dependencies and tooling
- Security and performance guidelines
- Deployment strategies
- Code style standards
- v1.0.3 - 🚀 NEW: Real-Time Memory Preservation! Every AI response triggers automatic checkpointing. Zero API costs, intelligent memory decay, no more lost conversations!
- v1.0.2 - 🏁 NEW: Session Management & AICF 3.0! Complete session finish/handoff system + 32 comprehensive templates + enhanced AI continuity!
- v1.0.1 - 🚀 NEW: Logic Agent Checkpoint Orchestrator! Zero API costs, ultra-fast processing, excellent information preservation!
- v1.0.0 - 🎯 Simplified to 7 essential files! Focus on what works with optional AICF format.
- v0.14.0 - Direct .aicf/ reading - ZERO manual steps! AI reads files directly, no copy/paste!
- v0.13.0 - AICF 2.0 - Universal AI Memory Protocol! 88% token reduction!
See CHANGELOG.md for complete version history.
# Auto-detect project type
npx aic init
# Or use specific technology template
npx aic init --template nextjs # Next.js/React projects
npx aic init --template python # Python projects
npx aic init --template rust # Rust projects
npx aic init --template go # Go projects
npx aic init --template java # Java/Spring Boot
npx aic init --template react # React projects
npx aic init --template vue # Vue.js projects
npx aic init --template fastapi # Python FastAPI
npx aic init --template django # Django projects
npx aic init --template devops # DevOps/Infrastructure
npx aic init --template ai_ml # AI/ML projects
# Customize for your project
vim .ai/project-overview.md
vim .ai/technical-decisions.md
# Commit to Git
git add .ai/ .ai-instructions NEW_CHAT_PROMPT.md
git commit -m "Add AI knowledge base"
# In your next AI chat, start with:
"Read .ai-instructions first, then help me with [your task]"💡 Tip: Use npx aic instead of npx create-ai-chat-context for shorter commands!
# Setup & Basic Usage
npx aic init # Initialize knowledge base (7 files)
npx aic universal # Setup Universal AI Memory for ALL platforms 🌍
npx aic migrate # Add missing .ai/ files
npx aic migrate --to-aicf # Convert to AICF 3.0 (85% token reduction)
npx aic search "query" # Find information in knowledge base
npx aic stats # View analytics and token usage
npx aic validate # Check knowledge base quality
npx aic config # Manage configuration
# 🕐 Detection-Hourglass-System (DHS) - NEW!
npx aic hourglass monitor # Start DHS background monitoring
npx aic hourglass stats # View hourglass session statistics
npx aic hourglass trigger # Manual trigger for testing
# 🤖 Logic Agent Checkpoint Orchestrator
npx aic checkpoint --demo # Test with demo data (instant)
npx aic checkpoint --file data.json --verbose # Process checkpoint
npx aic memory-decay --verbose # Apply intelligent memory decay
# 🏁 Session Management (NEW!)
npx aic finish --aicf # Finish session & migrate to AICF 3.0
npx aic monitor # Check token usage
npx aic monitor --check-finish # Check if session should endWorkflows:
- Manual: Ask the AI to update the
.ai/files at session end - Automated: Use
npx aic finish --aicffor complete session wrap-up with handoff
The breakthrough: Auto-detects conversation chunks between user inputs with zero manual intervention. Works universally across all AI platforms!
🕐 Hourglass Lifecycle (WORKING!):
User Input → 🕐 Hourglass Starts → AI Responds → User Input → 🕐 Hourglass Flips
│ │
└──────── Dynamic Token Counting (REAL-TIME) ────────────┼─────┐
│
🤖 6 Agent Processing (5ms)
│
💾 .ai/.aicf File Updates
│
✅ PIPELINE CONNECTED!
Key Innovation: AI code execution = user input detection
- Every time you send input → AI runs code → Auto-trigger fires
- Universal compatibility - works on any platform where AI executes code
- Natural boundaries - conversation chunks end at user input
- Dynamic sizing - chunks adapt to conversation length (50-5000+ tokens)
# Start background monitoring (for testing)
node src/hourglass.js monitor
# View session statistics
node src/hourglass.js stats
# Manual trigger (for testing)
node src/hourglass.js trigger "user message" "ai response"
# Auto-trigger from AI code (the magic!)
const { autoTrigger } = require('./src/hourglass');
await autoTrigger('user input', 'ai response');| Platform | DHS Compatible | Method |
|---|---|---|
| Warp AI | ✅ Perfect | Code execution auto-trigger |
| Claude Projects | ✅ Perfect | Code execution auto-trigger |
| ChatGPT Code Interpreter | ✅ Perfect | Code execution auto-trigger |
| Cursor AI | ✅ Perfect | Code execution auto-trigger |
| GitHub Copilot | ✅ Perfect | Code execution auto-trigger |
| Any AI with code execution | ✅ Perfect | Universal compatibility |
Why DHS is Revolutionary:
- ✅ Zero manual intervention - completely automatic
- ✅ Universal compatibility - works with ALL AI platforms
- ✅ Natural conversation chunks - respects user interaction boundaries
- ✅ Dynamic sizing - adapts to conversation complexity
- ✅ Zero API costs - pure logic-based detection
- ✅ Lightning fast - 5-6ms processing per chunk
| Metric | Achievement | Status |
|---|---|---|
| Auto-Detection | 13 chunks captured automatically | ✅ WORKING |
| Processing Speed | 5-6ms per chunk | ✅ VERIFIED |
| Data Pipeline | Real conversation → Agents → Files | ✅ CONNECTED |
| Token Processing | 912+ tokens across session | ✅ LIVE |
| File Updates | Both .ai/ and .aicf/ formats | ✅ CONFIRMED |
| Zero Cost | No API calls, pure logic | ✅ ACHIEVED |
| Universal Compatibility | All AI platforms supported | ✅ READY |
Revolutionary approach: Automatically capture every AI exchange with zero API costs using 6 specialized logic agents. No more lost context!
- Triggers after every AI response (not 20k token batches)
- Zero cost - Logic agents run locally without API calls
- Real-time updates to both
.ai/and.aicf/files - Intelligent memory decay prevents file overflow
# Process checkpoint with demo data (test the system)
npx aic checkpoint --demo
# Process real conversation checkpoint
npx aic checkpoint --file checkpoint.json --verbose
# Apply intelligent memory decay (automatic in v1.0.3+)
npx aic memory-decay --verbose
# Run comprehensive test
npm run test:checkpoint| Aspect | AI Compression | Logic Agent Orchestrator |
|---|---|---|
| Cost | $0.03-0.15 per checkpoint | $0.00 forever |
| Speed | 30-45 seconds | ~10 milliseconds |
| Information Preserved | 60-75% | Nearly 100% |
| Quality | Variable | Consistent |
| API Dependency | Required | None (works offline) |
| Vendor Lock-in | Yes | None (universal) |
Architecture: 6 specialized agents run in parallel:
- ConversationParserAgent - Extracts conversation flow
- DecisionExtractorAgent - Identifies key decisions
- InsightAnalyzerAgent - Captures breakthroughs
- StateTrackerAgent - Monitors project progress
- FileWriterAgent - Outputs dual formats (AICF + Markdown)
- MemoryDropOffAgent - Applies intelligent decay strategy
Result: Excellent context preservation with zero ongoing costs. See examples/checkpoint-example.json for sample data format.
We believe AICF (AI Continuity Format) represents the future of AI memory persistence. Our vision is for .aicf to become a widely-adopted standard across the tech industry.
🎯 Built for AI, by AI - Designed specifically for optimal AI comprehension and processing
⚡ Ultra-efficient - 85% token reduction while preserving 100% information integrity
🔗 Relationship mapping - CONTEXT_REFS and IMPACT_SCORE enable intelligent prioritization
🏗️ Structured intelligence - Schema-based format with confidence scoring and temporal tracking
🌐 Universal compatibility - Works with any AI assistant (ChatGPT, Claude, Copilot, Cursor, Warp, etc.)
💰 Zero cost - No API dependencies, works completely offline
- IDEs natively support
.aicffiles for AI context - AI platforms adopt AICF as standard memory format
- Development teams share project context through
.aicffiles - Open source projects include
.aicf/directories for contributor onboarding - AI tools interoperate seamlessly using AICF format
Join the movement! Help us make AICF the universal standard for AI memory by:
- ⭐ Starring this project on GitHub
- 📢 Sharing AICF with your development teams
- 🔧 Contributing to the AICF specification
- 💡 Building tools that support AICF format
Together, we can solve AI context loss forever. 🚀
Optional configuration for customizing the tool:
# View current configuration
npx aic config
# Set preferred AI model for token reports (optional)
npx aic config set preferredModel "Claude Sonnet 4.5"Configuration is stored per-project in .ai/config.json. See CONFIGURATION.md for details.
- COMMANDS.md - Complete command reference with examples
- CONFIGURATION.md - Detailed configuration guide
- CHANGELOG.md - Version history and updates
These files are created in your project:
📁 .ai/ Directory (Human-readable files):
.ai/README.md- Overview of the knowledge base system.ai/project-overview.md- Project context and conventions (AI config).ai/conversation-log.md- Chat history and decisions.ai/technical-decisions.md- Architecture and technical choices.ai/next-steps.md- Current priorities and tasks.ai/design-system.md- Design patterns and conventions.ai/code-style.md- Coding standards and guidelines
📄 Root files:
.ai-instructions- Instructions for AI assistantsNEW_CHAT_PROMPT.md- Quick reference for the one-liner prompt
🚀 Optional AICF 3.0 (run npx aic finish --aicf):
.aicf/conversations.aicf- Ultra-compressed chat history (85% token reduction).aicf/decisions.aicf- Technical decisions in structured format.aicf/tasks.aicf- Project tasks with priority scoring.aicf/issues.aicf- Known issues (if any).aicf/index.aicf- Fast lookup index.aicf/.meta- Project metadata
MIT
Made with ❤️ for developers who use AI assistants daily
🎆 Incredible Journey: From idea (Sept 30, 8pm) to 3,300+ downloads in 3.5 days! Created by a developer with 7 months of coding experience. Next milestone: 1,000,000 downloads! 🎯🚀
Questions or issues? Open an issue on GitHub