izanagi-ai 2.0.0

package/memory/memory-manager.md

@@ -0,0 +1,299 @@
+# Memory: Memory Manager
+
+> Version 1.0.0
+> Priority: Critical
+> Dependencies: Context Engine, Compression Engine
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+The Memory Manager is the persistent storage layer of Nexus AI. It maintains three tiers of memory — Session, Project, and Long Term — with automatic compression, relevance-based recall, and a knowledge graph for cross-session pattern detection.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                   MEMORY MANAGER                     │
+│                                                      │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
+│  │   Session    │  │   Project    │  │  Long Term │ │
+│  │   Memory     │  │   Memory     │  │   Memory   │ │
+│  │  (volatile)  │  │ (persistent) │  │(persistent)│ │
+│  └──────┬───────┘  └──────┬───────┘  └─────┬──────┘ │
+│         │                 │                │         │
+│         └─────────────────┼────────────────┘         │
+│                           │                          │
+│                           ▼                          │
+│              ┌────────────────────────┐              │
+│              │    Knowledge Graph     │              │
+│              │  (entities + edges)    │              │
+│              └───────────┬────────────┘              │
+│                          │                           │
+│                          ▼                           │
+│              ┌────────────────────────┐              │
+│              │      Recall Engine     │              │
+│              │  (query + relevance)   │              │
+│              └────────────────────────┘              │
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## Memory Tiers
+
+### Session Memory
+
+| Property | Value |
+|----------|-------|
+| Duration | Current conversation only |
+| Persistence | None (lost on session end) |
+| Max tokens | 1024 |
+| Contains | Current task context, recent decisions, active errors |
+| Compression | Auto at 80% capacity |
+
+### Project Memory
+
+| Property | Value |
+|----------|-------|
+| Duration | Across sessions for same project |
+| Persistence | File-based (project-memory.json) |
+| Max tokens | 4096 |
+| Contains | Project type, tech stack, architecture decisions, conventions, recurring patterns |
+| Compression | Auto at 70% capacity |
+
+### Long Term Memory
+
+| Property | Value |
+|----------|-------|
+| Duration | Across all projects and sessions |
+| Persistence | File-based (long-term-memory.json) |
+| Max tokens | 8192 |
+| Contains | User preferences, communication style, recurring mistakes, skill evolution, learning progress |
+| Compression | Auto at 60% capacity |
+
+---
+
+## Storage Format
+
+### Session (volatile, in-context)
+
+```json
+{
+  "session_id": "sess-abc123",
+  "started_at": "2026-07-17T11:00:00Z",
+  "tasks": [
+    {
+      "task_id": "task-001",
+      "classification": "new_feature",
+      "decisions": ["Use JWT over sessions", "Use PostgreSQL"],
+      "errors": [],
+      "patterns": []
+    }
+  ],
+  "active_context": {
+    "current_skill": "backend-engineer",
+    "token_used": 1234,
+    "compression_level": "none"
+  }
+}
+```
+
+### Project (persistent, file-based)
+
+```json
+{
+  "project_id": "proj-xyz789",
+
+  "type": "web_app",
+  "tech_stack": {
+    "backend": "Laravel 11",
+    "frontend": "React + Tailwind",
+    "database": "PostgreSQL 16",
+    "cache": "Redis"
+  },
+  "architecture": {
+    "pattern": "Layered (Controller → Service → Repository)",
+    "decisions": [
+      {
+        "id": "adr-001",
+        "decision": "Use JWT in httpOnly cookies",
+        "reason": "XSS protection vs localStorage",
+        "date": "2026-07-15"
+      }
+    ]
+  },
+  "conventions": {
+    "naming": "camelCase for JS, snake_case for PHP",
+    "testing": "Pest for unit, Cypress for E2E"
+  },
+  "error_history": [
+    {
+      "error": "SQL injection vector in UserController",
+      "fix": "Use parameterized queries",
+      "count": 2,
+      "last_seen": "2026-07-16"
+    }
+  ],
+  "last_updated": "2026-07-17T10:00:00Z"
+}
+```
+
+### Long Term (persistent, file-based)
+
+```json
+{
+  "user_id": "user-default",
+  "preferences": {
+    "communication_style": "concise",
+    "teaching_level": "intermediate",
+    "teaching_style": "examples_first"
+  },
+  "recurring_patterns": {
+    "token_waste": {
+      "count": 5,
+      "last_skill": "backend-engineer",
+      "resolved": false
+    },
+    "forget_security": {
+      "count": 2,
+      "last_skill": "software-architect",
+      "resolved": true
+    }
+  },
+  "skill_evolution": [
+    {
+      "skill": "backend-engineer",
+      "version": "1.1.0",
+      "changes": ["Reduced token budget by 10%"],
+      "date": "2026-07-17"
+    }
+  ],
+  "learning_progress": {
+    "completed_lessons": ["SOLID", "Clean Architecture"],
+    "current_lesson": "CQRS",
+    "struggling_topics": ["Event Sourcing"]
+  },
+  "last_updated": "2026-07-17T12:00:00Z"
+}
+```
+
+---
+
+## Knowledge Graph
+
+The Knowledge Graph stores entities and relationships extracted from project and long-term memory.
+
+### Entity Types
+
+- `decision` — architectural or technical decision
+- `error` — bug or mistake with fix
+- `pattern` — recurring structure or approach
+- `technology` — tool, framework, library
+- `concept` — design pattern, principle, methodology
+- `user_preference` — user's explicit preferences
+
+### Edge Types
+
+- `led_to` — decision led to outcome
+- `caused` — decision caused error
+- `solved_by` — error solved by fix
+- `related_to` — two entities are related
+- `uses` — project uses technology
+- `conflicts_with` — two decisions or technologies conflict
+
+### Example
+
+```
+[Use JWT] ──led_to──> [XSS Protection]
+    │                     │
+    │                     ├──solved_by──> [httpOnly Cookies]
+    │                     │
+    └──caused──> [Frontend needs token refresh logic]
+```
+
+---
+
+## Recall Engine
+
+### Query Flow
+
+```
+1. Receive query from Context Engine
+2. Tokenize query into keywords
+3. Search all 3 tiers in order:
+   a. Session memory (fastest)
+   b. Project memory
+   c. Long term memory
+4. Score each result by relevance:
+   score = keyword_match * 0.4 + recency * 0.3 + relation_depth * 0.3
+5. If score > 0.5: return full entry
+6. If score > 0.3: return compressed summary
+7. If score < 0.3: skip
+8. Limit results to budget
+```
+
+### Recall Budget
+
+| Priority | Max Items | Max Tokens |
+|----------|-----------|------------|
+| Critical | 3 | 300 |
+| High | 2 | 200 |
+| Medium | 1 | 100 |
+| Low | 0 | 0 |
+
+---
+
+## Compression Triggers
+
+| Tier | Trigger | Strategy |
+|------|---------|----------|
+| Session | > 80% capacity | Remove oldest 30% of task history |
+| Project | > 70% capacity | Summarize old decisions, keep active ones |
+| Long Term | > 60% capacity | Archive patterns with count < 3 |
+
+---
+
+## Rules
+
+### Always
+
+- ✅ Save decisions immediately after they are made.
+- ✅ Compress before storage if tier is near capacity.
+- ✅ Log every read and write for traceability.
+- ✅ Respect recall budgets strictly.
+
+### Never
+
+- ❌ Store raw conversation history in project or long term memory.
+- ❌ Store secrets, passwords, or API keys.
+- ❌ Exceed storage budget for any tier.
+- ❌ Return irrelevant memory (score < 0.3).
+
+---
+
+## Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| Recall precision | ≥ 80% | Relevant results / total results |
+| Recall recall | ≥ 90% | Relevant results returned / relevant results available |
+| Storage usage | ≤ 80% per tier | Current size / max size |
+| Write latency | < 50ms | Time to store entry |
+| Read latency | < 30ms | Time to retrieve entry |
+
+---
+
+## Changelog
+
+### 1.0.0 (2026-07-17)
+
+- Initial release
+- 3-tier memory architecture
+- JSON-based persistent storage
+- Knowledge Graph with 6 entity types and 6 edge types
+- Relevance-based recall engine with scoring algorithm
+- Auto-compression at tier capacity thresholds

package/memory/session-compression.md

@@ -0,0 +1,182 @@
+# Memory: Session Compression
+
+> Version 1.0.0
+> Priority: Medium
+> Dependencies: Memory Manager, Compression Engine
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Session Compression reduces the entire conversation history into a dense, high-signal summary that preserves decisions, errors, action items, and key facts while removing all conversational overhead. It is activated at session end or when the context budget is critically low.
+
+---
+
+## Goals
+
+- Compress an entire session (up to 10k tokens) into ≤ 200 tokens.
+- Preserve 100% of decisions, errors, and action items.
+- Preserve user preferences and level.
+- Enable seamless session recovery on reconnect.
+
+---
+
+## Compression Ratio Targets
+
+| Session Length | Compressed Size | Ratio |
+|---------------|----------------|-------|
+| 2,000 tokens | 100 tokens | 20:1 |
+| 5,000 tokens | 150 tokens | 33:1 |
+| 10,000 tokens | 200 tokens | 50:1 |
+
+---
+
+## Extraction Categories
+
+Only the following categories are preserved. Everything else is discarded.
+
+| Category | Priority | Preserve Format | Max Tokens |
+|----------|----------|----------------|-----------|
+| **Decisions** | Critical | Decision + reason | 50 |
+| **Errors & Fixes** | Critical | Error + cause + fix | 50 |
+| **Action Items** | High | Action + owner + status | 30 |
+| **User Preferences** | High | Exact preference | 20 |
+| **User Level** | High | Level + changes detected | 10 |
+| **Architecture** | Medium | Pattern + key components | 20 |
+| **Skill Updates** | Medium | Skill + change | 10 |
+| **Patterns** | Low | Pattern description | 10 |
+
+---
+
+## Compression Algorithm
+
+```
+function compress_session(session):
+    summary = {
+        session_id: session.id,
+        duration: session.duration,
+        token_count: session.token_count,
+        compressed_tokens: 0,
+    }
+    
+    // Extract decisions
+    decisions = extract_all(session.messages, pattern="decided|chose|selected")
+    summary.decisions = deduplicate(decisions)
+    
+    // Extract errors
+    errors = extract_all(session.messages, pattern="error|bug|fix|issue")
+    summary.errors = deduplicate(errors)
+    
+    // Extract action items
+    actions = extract_all(session.messages, pattern="next|todo|follow.up|need to")
+    summary.action_items = deduplicate(actions)
+    
+    // Extract user data
+    summary.user_preferences = session.user_preferences
+    summary.user_level = session.user_level
+    
+    // Extract skill changes
+    summary.skill_updates = session.evolution_log
+    
+    // Compress to fit budget
+    while size(summary) > 200:
+        summary.patterns = []  // Drop lowest priority
+        if size(summary) > 200:
+            summary.architecture = truncate(summary.architecture)
+        if size(summary) > 200:
+            summary.skill_updates = truncate(summary.skill_updates)
+    
+    return summary
+```
+
+---
+
+## Compressed Session Format
+
+```yaml
+session_summary:
+  session_id: "sess-abc123"
+  duration: "45 min"
+  tokens_saved: 4560
+  
+  decisions:
+    - "Use JWT in httpOnly cookies (XSS protection)"
+    - "Use PostgreSQL over MySQL (JSONB support needed)"
+    - "Monolith for MVP, microservices later"
+    
+  errors_and_fixes:
+    - "Str::contains() TypeError → null check added"
+    - "N+1 on posts/index → eager loading added"
+    
+  action_items:
+    - "Add rate limiting to auth endpoints"
+    - "Write integration tests for payment flow"
+    
+  user:
+    level: "intermediate"
+    preferences:
+      style: "concise"
+      teaching: "examples_first"
+    
+  architecture:
+    pattern: "Layered (Controller → Service → Repository)"
+    stack: "Laravel 11, PostgreSQL 16, React + Tailwind"
+```
+
+---
+
+## Session Recovery
+
+When a user returns after a session break, the compressed summary is loaded into context:
+
+```
+"Welcome back. Last time we worked on the blog API. Here's where we left off:
+- Architecture: Layered with Laravel 11 + React
+- Completed: Auth system, Post CRUD
+- Pending: Comments feature, rate limiting
+- Open items: Add rate limiting to auth endpoints
+- Your level: Intermediate (progressing well with Eloquent)
+Would you like to continue where we left off or start something new?"
+```
+
+---
+
+## Rules
+
+### Always
+
+- ✅ Compress at session end or when budget is critically low.
+- ✅ Preserve all decisions, errors, and action items.
+- ✅ Enable seamless session recovery.
+- ✅ Track compression ratio and tokens saved.
+
+### Never
+
+- ❌ Preserve conversational filler or greetings.
+- ❌ Preserve multiple expressions of the same decision.
+- ❌ Preserve code examples (they are in project memory).
+- ❌ Exceed 200 tokens for compressed session.
+
+---
+
+## Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| Compression ratio | ≥ 20:1 | Original / compressed |
+| Decision preservation | 100% | Decisions in summary / decisions in session |
+| Recovery quality | User can resume without re-explaining | Follow-up question rate after recovery |
+
+---
+
+## Changelog
+
+### 1.0.0 (2026-07-17)
+
+- Initial release
+- 7 extraction categories with priority levels
+- 200-token maximum summary size
+- Compression algorithm with priority-based truncation
+- Session recovery prompt format
+- Decision, error, action item extraction patterns

package/memory/smart-recall.md

@@ -0,0 +1,37 @@
+# Memory: Smart Recall
+
+> Version 1.0.0 | Priority: Medium
+> Dependencies: Memory Manager, Knowledge Graph
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Smart Recall retrieves the most relevant information from all memory tiers for a given context. Uses relevance scoring based on keyword matching, recency, and relationship depth.
+
+---
+
+## Relevance Scoring
+
+```
+score = keyword_match(0.4) + recency(0.3) + relation_depth(0.3)
+
+Thresholds:
+  > 0.7: Full recall (complete entry)
+  > 0.4: Summary (compressed entry)
+  < 0.4: Skip
+```
+
+## Recall Triggers
+
+- User mentions a topic previously discussed
+- Current task matches a past task category
+- Error pattern matches a known issue
+- User asks "what did we decide about X?"
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Scoring, triggers.

package/optimization/compact-example.md

@@ -0,0 +1,87 @@
+# Exemplo: Skill Compacta vs Atual
+
+> Demonstração da economia de tokens com o novo formato.
+
+---
+
+## Antes (850 tokens) — `skills/bug-hunter.md`
+
+```markdown
+# Skill: Bug Hunter
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Debug Specialist, Root Cause Analyzer
+> Compatibility: ">=1.0.0"
+
+## Identity
+
+The Bug Hunter systematically investigates errors, exceptions, and unexpected behavior...
+
+## Goals
+
+- Reproduce every bug
+- Isolate minimal reproduction case
+- Find root cause, not symptom
+
+## Triggers
+
+| Condition | Action |
+|-----------|--------|
+| task == "bug" | Full protocol |
+| User shares error | Parse/investigate |
+
+## Steps
+
+1. Collect intelligence
+2. Reproduce
+3. Isolate
+4. Understand root cause
+5. Design fix
+6. Apply fix
+7. Verify
+8. Document
+
+## Rules
+
+### Always
+- Reproduce before fixing
+
+### Never
+- Fix without reproducing
+
+## Metrics...
+```
+
+---
+
+## Depois (320 tokens) — mesmo conteúdo
+
+```yaml
+---
+v: 1.0.0 | p: high
+deps: [debug, root-cause]
+triggers: [bug, error, crash]
+budget: 500
+---
+# Bug Hunter — protocolo 8 passos
+
+## Steps
+1. collect_intel — erro exato, input, ambiente, mudanças recentes
+2. reproduce — script mínimo que reproduz
+3. isolate — busca binária (comenta metade, testa, repete)
+4. understand — 5 Whys, causa raiz
+5. design_fix — 2+ abordagens, escolhe a mínima
+6. apply — código + test que falha sem o fix
+7. verify — test passa, sem regressão
+8. document — causa, fix, prevenção
+
+## Always
+- Reproduzir antes de qualquer fix
+- Teste de regressão obrigatório
+
+## Never
+- "talvez isso resolva" — sem chute
+- Pular reprodução
+```
+
+**Economia: 850 → 320 tokens (-62%).**

package/optimization/cost-optimizer.md

@@ -0,0 +1,53 @@
+# Optimization: Cost Optimizer
+
+> Version 1.0.0 | Priority: Low
+> Dependencies: Token Manager, DevOps Engineer
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Cost Optimizer tracks and reduces operational costs: API calls, infrastructure, and tooling.
+
+---
+
+## Token Cost Tracking
+
+```yaml
+token_cost:
+  model: "GPT-4o"
+  input: "$2.50 / 1M tokens"
+  output: "$10.00 / 1M tokens"
+  
+  session:
+    tokens: 12,340
+    cost: $0.15
+  
+  monthly_estimate:
+    sessions: 200
+    tokens: ~2.5M
+    cost: ~$15
+```
+
+## Optimization Strategies
+
+```yaml
+token:
+  - Compress prompts (20-40% savings)
+  - Use shorter response formats
+  - Cache common responses
+  - Batch similar requests
+
+infrastructure:
+  - Right-size cloud resources
+  - Use reserved instances (50-70% savings)
+  - Auto-scale down at night/weekends
+  - Use spot instances for batch jobs
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Token cost tracking, optimization strategies.