# Feynman — Companion Agent Brain for Persistent Context

> A context engine that gives AI coding agents persistent memory and reasoning capabilities, enabling them to maintain understanding across long sessions and complex multi-file tasks.

## Install

Save as a script file and run:

# Feynman — Companion Agent Brain for Persistent Context

## Quick Use
```bash
npm install -g @companion-inc/feynman

# Initialize Feynman in your project
feynman init

# Start the context engine alongside your coding agent
feynman serve --port 8787
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-6f4d1b7b
Author: Script Depot