Feynman — Companion Agent Brain for Persistent Context

Introduction

Feynman acts as a persistent context brain for AI coding agents. Named after the physicist known for deep understanding, it indexes your codebase, tracks conversation history, and provides structured context retrieval so agents maintain coherence across long development sessions without losing track of decisions made earlier.

What Feynman Does

• Indexes codebases into a searchable knowledge graph
• Maintains persistent session memory across agent restarts
• Provides context-aware retrieval for coding agent queries
• Tracks architectural decisions and rationale over time
• Integrates with multiple agent frameworks via a standard API

Architecture Overview

Feynman runs as a local TypeScript server that watches your project directory. It builds an incremental index using AST parsing and embedding-based chunking, stored in a local SQLite database. When an agent queries for context, Feynman performs hybrid search (keyword + semantic) and returns ranked results with source locations. A decision log captures agent reasoning chains for future reference.

Self-Hosting & Configuration

• Requires Node.js 18+ and runs as a local daemon
• Configure via feynman.config.json for index scope, ignored paths, and model preferences
• Supports local embeddings via Ollama or cloud providers for embedding generation
• Stores all data locally in .feynman/ directory within your project
• Resource usage scales with codebase size; typical projects use under 500MB of disk

Key Features

• Incremental codebase indexing with AST-aware chunking
• Hybrid search combining keyword matching and semantic similarity
• Decision log that preserves architectural reasoning across sessions
• Agent-agnostic REST API compatible with any tool-use protocol
• Offline-capable with local embedding models

Comparison with Similar Tools

• Cody by Sourcegraph — cloud-hosted code context; Feynman is local-first and agent-agnostic
• Cursor codebase indexing — IDE-specific; Feynman works with any agent or editor
• RAGFlow — document-oriented RAG; Feynman is purpose-built for code context
• Continue — IDE assistant; Feynman is a standalone context layer, not an agent itself

FAQ

Q: Does Feynman work with any coding agent? A: Yes, it exposes a REST API that any agent can call for context retrieval. Adapters exist for popular frameworks.

Q: How large a codebase can it handle? A: Feynman has been tested on repositories with over 100,000 files. Indexing is incremental, so only changed files are re-processed.

Q: Does it require a GPU? A: No. Local embeddings run on CPU via Ollama. GPU acceleration is optional and improves indexing speed for large repos.

Q: Where is the data stored? A: All index data stays in a .feynman/ directory inside your project. Nothing leaves your machine unless you configure a cloud embedding provider.

Sources

• https://github.com/companion-inc/feynman