neo

---

Neo

A self-improving code reasoning engine that learns from experience using persistent semantic memory. Neo uses multi-agent reasoning to analyze code, generate solutions, and continuously improve through feedback loops.

• Fact-Based Memory: Learns from every solution attempt using a scoped, supersession-based fact store
• Semantic Retrieval: Vector search finds relevant facts via Jina Code embeddings
• Code-First Generation: No diff parsing failures
• Local Storage: Privacy-first JSON storage in ~/.neo/facts/ directory
• Model-Agnostic: Works with any LM provider
• Available as a Claude Code Plugin: Integrates seamlessly with Anthropic's Claude models and CLI.

Why Neo? Why Care?

If you've been Vibe Coding, then Vibe Planning, then Context Engineering, and on and on, you have likely hit walls where the models are both powerful and limited, brilliant and incompetent, wise and ignorant, humble yet overconfident.

Worse, your speedy AI Code Assistant sometimes goes rogue and overwrites key code in a project, or writes redundant code even after just reading documentation and the source code, or violates your project's patterns and design philosophy.... It can be infuriating. Why doesn't the model remember? Why doesn't it learn? Why can't it keep the context of the code patterns and tech stack? ... -> This is what Neo is designed to solve.

Neo is the missing context layer for AI Code Assistants. It learns from every solution attempt, using vector embeddings to retrieve relevant patterns for new problems. It then applies the learned patterns to generate solutions, and continuously improves through feedback loops.

Table of Contents

• Design Philosophy
• How It Works
• Quick Start
• Claude Code Plugin
• Codex Plugin
• Works Alongside Your AI Tools
  • Quick Examples
• Installation
  • From PyPI (Recommended)
  • From Source (Development)
  • Dependencies
  • Optional: LM Provider
• Usage
  • CLI Interface
  • Timeout Requirements
  • Output Format
  • Personality System
• Architecture
  • Fact-Based Memory
  • Output Schemas
  • Storage Architecture
• Performance
• Configuration
  • CLI Configuration Management
  • Environment Variables
• LM Adapters
  • OpenAI (Default)
  • Anthropic
  • Google
  • Ollama
• Extending Neo
  • Add a New LM Provider
• Key Features
• Development
  • Running Tests
• Research & References
  • Academic Papers
  • Technologies
• License
• Contributing
• Changelog

Design Philosophy

Fact-Based Learning: Neo builds a semantic memory of facts — constraints, architectural decisions, patterns, review learnings, decisions, known unknowns, and failures — using vector embeddings for retrieval.

Code-First Output: Instead of generating diffs that need parsing, Neo outputs executable code blocks directly, eliminating extraction failures.

Scoped Storage: Facts are scoped to global, organization, or project level, stored locally in ~/.neo/facts/ for privacy and offline access.

Model-Agnostic: Works with OpenAI, Anthropic, Google, local models, or Ollama via a simple adapter interface.

How It Works

User Problem → Neo CLI → Semantic Retrieval → Reasoning → Code Generation
                           ↓
                    [Vector Search]
                    [Pattern Matching]
                    [Confidence Scoring]
                           ↓
                    Executable Code + Memory Update