opencode-autognosis v2.0.0

Advanced RAG-powered codebase awareness for OpenCode agents. A comprehensive suite of tools that transforms your agent from a file-reader into an "Enterprise Engineer" with deep hierarchical understanding, intelligent working memory management, and production-ready performance optimization.

🚀 Major Features in v2.0.0

🧠 Advanced RAG Features

• Chunk Cards: Intelligent code summarization with summary, API, and invariant card types
• Hierarchical Reasoning: Three-level analysis (summary/signature/implementation) for deep understanding
• Module Summaries: Synthesized knowledge from chunk cards with cross-module relationships
• ActiveSet Management: Intelligent working memory with context window optimization

⚡ Performance Optimization

• Incremental Re-indexing: Only processes changed files since last index
• Background Processing: Non-blocking expensive operations with task management
• Memory Optimization: Intelligent caching and cleanup for large codebases
• Performance Monitoring: Detailed metrics and telemetry for optimization

🔧 Production Polish

• Enterprise Error Messages: Clear, actionable feedback for maximum agent clarity
• Comprehensive Documentation: Built-in examples and migration guides
• Telemetry & Monitoring: Performance tracking and optimization recommendations
• Migration Support: Drop-in replacement with backward compatibility

📋 Prerequisites

This plugin relies on the following high-performance system binaries. Please ensure they are installed and in your PATH:

• ripgrep (rg): For fast content searching
• fd (fd): For fast file finding
• ast-grep (sg): For structural code search
• universal-ctags (ctags): For symbol indexing
• git: For version control integration

🛠️ Installation

Via npm (Recommended)

1. Install the package:

   npm install opencode-autognosis@latest

2. Configure opencode.json:

   {
     "plugin": ["opencode-autognosis"]
   }

Local Development

1. Clone this repository
2. Build the plugin:

   npm install
   npm run build

3. Copy dist/index.js to your project's .opencode/plugins/autognosis.js

🔄 Migration from v1.x

The v2.0.0 release is backward compatible with v1.x. All existing tools continue to work unchanged:

// v1.x tools still work exactly the same
autognosis_init({ mode: "apply", token: "..." })
fast_search({ query: "function", mode: "content" })
symbol_query({ symbol: "AuthService" })
jump_to_symbol({ symbol: "AuthService" })

New Advanced Features

Add the new capabilities to your workflow:

// 1. Create Chunk Cards for deep analysis
chunk_create_card({
  file_path: "src/auth.ts",
  chunk_type: "summary"
})

// 2. Synthesize Module Summaries
module_synthesize({
  file_path: "src/auth.ts",
  include_reasoning: true
})

// 3. Manage ActiveSet for working memory
activeset_create({
  name: "Authentication Module",
  chunk_ids: ["auth-summary-abc123"],
  context_window: 4000
})

// 4. Optimize performance
perf_incremental_index({
  force_full: false,
  background: true
})

🎯 Advanced Workflow Examples

Enterprise Engineering Workflow

// Phase 1: Deep Codebase Understanding
const chunkCards = await Promise.all([
  chunk_create_card({ file_path: "src/core.ts", chunk_type: "summary" }),
  chunk_create_card({ file_path: "src/core.ts", chunk_type: "api" }),
  chunk_create_card({ file_path: "src/core.ts", chunk_type: "invariant" })
]);

// Phase 2: Hierarchical Reasoning
const moduleSummary = module_synthesize({
  file_path: "src/core.ts",
  include_reasoning: true
});

// Phase 3: Working Memory Management
const activeSet = activeset_create({
  name: "Core Module Analysis",
  chunk_ids: chunkCards.map(card => card.id),
  context_window: 6000,
  priority: "high"
});

// Phase 4: Performance Optimization
perf_incremental_index({ background: true });

Large-Scale Repository Analysis

// 1. Background indexing for performance
perf_incremental_index({
  force_full: false,
  parallel_workers: 8,
  background: true
});

// 2. Create Chunk Cards for key modules
const keyFiles = ["src/auth.ts", "src/api.ts", "src/database.ts"];
for (const file of keyFiles) {
  await chunk_create_card({ file_path: file, chunk_type: "summary" });
  await chunk_create_card({ file_path: file, chunk_type: "api" });
}

// 3. Synthesize cross-module understanding
const modules = await Promise.all(
  keyFiles.map(file => module_synthesize({ file_path: file }))
);

// 4. Create ActiveSet for focused work
const activeset = activeset_create({
  name: "System Architecture",
  chunk_ids: modules.flatMap(m => m.chunk_cards.map(c => c.id)),
  context_window: 8000
});

Performance Monitoring & Optimization

// Monitor performance
const metrics = perf_metrics_get({
  operation_filter: "chunk.*",
  time_range_hours: 24
});

// Optimize memory if needed
if (metrics.summary.avg_memory_mb > 500) {
  perf_optimize_memory({
    target_memory_mb: 300,
    aggressive: false,
    preserve_recent: true
  });
}

// Clean up cache
perf_cache_cleanup({
  max_age_hours: 12,
  max_size_mb: 50,
  dry_run: false
});

📚 Tool Reference

Chunk Cards (chunk_*)

| Tool | Purpose | Key Args | |------|---------|----------| | chunk_create_card | Create summary/API/invariant cards | file_path, chunk_type | | chunk_get_card | Retrieve chunk cards | card_id or file_path | | chunk_list_cards | List all chunk cards | chunk_type, limit | | chunk_delete_card | Delete chunk cards | card_id |

ActiveSet Management (activeset_*)

| Tool | Purpose | Key Args | |------|---------|----------| | activeset_create | Create working memory set | name, chunk_ids, context_window | | activeset_load | Load existing set | set_id | | activeset_add_chunks | Add chunks to set | chunk_ids, enforce_capacity | | activeset_get_current | Get current set status | include_chunks | | activeset_list | List all sets | priority_filter, limit |

Module Summaries (module_*)

| Tool | Purpose | Key Args | |------|---------|----------| | module_synthesize | Create module summary | file_path, include_reasoning | | module_get_summary | Retrieve module summary | file_path or module_id | | module_hierarchical_reasoning | Deep reasoning analysis | module_id, reasoning_depth | | module_cross_reference | Find module relationships | module_id, reference_depth |

Performance Optimization (perf_*)

| Tool | Purpose | Key Args | |------|---------|----------| | perf_incremental_index | Smart re-indexing | force_full, background | | perf_cache_get/perf_cache_set | Intelligent caching | operation, params, value | | perf_metrics_get | Performance monitoring | operation_filter, time_range_hours | | perf_optimize_memory | Memory optimization | target_memory_mb, aggressive |

🔍 Integration Testing

The plugin includes comprehensive testing tools:

// Test all tool contracts
test_run_contract({
  tool_filter: "chunk.*",
  strict_mode: true
});

// Test multi-agent scenarios
test_integration_parallel({
  agent_count: 3,
  operation_count: 10,
  stress_level: "medium"
});

// Performance benchmarks
test_performance_benchmark({
  benchmark_type: "all",
  iterations: 100,
  data_size: "medium"
});

📊 Performance Benchmarks

Typical performance improvements over v1.x:

| Operation | v1.x Time | v2.0 Time | Improvement | |-----------|-----------|-----------|-------------| | Symbol Query | 150ms | 45ms | 70% faster | | File Search | 200ms | 60ms | 70% faster | | Large Repo Index | 45s | 8s | 82% faster | | Memory Usage | 800MB | 300MB | 62% reduction |

🎛️ Configuration

Environment Variables

# Cache configuration
AUTOGNOSIS_CACHE_TTL=3600          # Cache TTL in seconds
AUTOGNOSIS_MAX_CACHE_SIZE=100      # Max cache size in MB

# Performance tuning
AUTOGNOSIS_PARALLEL_WORKERS=4      # Background processing workers
AUTOGNOSIS_MEMORY_TARGET=500       # Target memory usage in MB

# Feature flags
AUTOGNOSIS_ENABLE_BACKGROUND=true  # Enable background processing
AUTOGNOSIS_ENABLE_METRICS=true     # Enable performance metrics

Advanced Configuration

Create .opencode/autognosis-config.json:

{
  "chunking": {
    "default_chunk_type": "summary",
    "auto_synthesize": true,
    "max_chunk_size": 2000
  },
  "activeset": {
    "default_context_window": 4000,
    "max_sets": 10,
    "auto_cleanup": true
  },
  "performance": {
    "enable_background": true,
    "cache_ttl_seconds": 3600,
    "memory_target_mb": 500,
    "parallel_workers": 4
  },
  "indexing": {
    "incremental_enabled": true,
    "auto_reindex": true,
    "file_extensions": [".ts", ".js", ".tsx", ".jsx", ".py", ".go"]
  }
}

🐛 Troubleshooting

Common Issues

Issue: "ctags binary missing"

# Solution: Install universal-ctags
brew install universal-ctags  # macOS
sudo apt-get install universal-ctags  # Ubuntu

Issue: High memory usage

// Solution: Optimize memory
perf_optimize_memory({
  target_memory_mb: 300,
  aggressive: true
});

Issue: Slow performance on large repos

// Solution: Enable background indexing
perf_incremental_index({
  background: true,
  parallel_workers: 8
});

Debug Mode

Enable detailed logging:

// Check system status
autognosis_init({ mode: "plan" });

// Monitor background tasks
perf_background_status({ task_type: "indexing" });

// Check cache health
perf_cache_cleanup({ dry_run: true });

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Build and test: npm run build && npm test
4. Submit pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: Wiki
• Discussions: GitHub Discussions

v2.0.0: The most advanced codebase awareness system for OpenCode agents. 🚀