Skip to content

README

Jump to bottom
hitchhiker edited this page Feb 3, 2026 · 1 revision

Fold Documentation

Complete documentation for Fold, a holographic memory system for development teams and AI agents.

📖 Documentation Map

Start here: Overview-Concepts — Understand what Fold is and why it matters

For Everyone

  1. Overview-Concepts (45 min read)

    • What is Fold?
    • Why "holographic"?
    • AI benefits (huge focus)
    • How it works
    • Key features
    • Architecture overview
    • Memory types
    • Fold vs. traditional approaches

  2. Getting-Started (15 min)

    • Install with Docker (recommended)
    • Install for local development
    • First steps: connect a repo
    • Connect Claude Code
    • Troubleshooting setup issues

For DevOps & Operators

  1. Configuration (30 min)

    • Environment variables (all required & optional)
    • LLM provider setup (Gemini, OpenRouter, OpenAI)
    • Auth providers (Google, GitHub, corporate OIDC)
    • Git integration (GitHub/GitLab webhooks)
    • Database & storage setup
    • Embedding models
    • Advanced configuration
    • Provider-specific setup guides

  2. Deployment-Operations (45 min)

    • Production architecture
    • Docker Compose (production-grade)
    • Nginx reverse proxy
    • Database management (PostgreSQL migration)
    • Qdrant scaling
    • Monitoring & observability (Prometheus, Grafana)
    • Performance tuning
    • Backup & disaster recovery
    • Security hardening
    • Scaling strategies
    • Operational checklists

For Developers & Architects

  1. Core-Concepts (40 min)

    • What is a memory?
    • Memory types deep dive
    • How embeddings & vectors work
    • The knowledge graph
    • Link types and relationships
    • How semantic search works
    • File attachments
    • Content hashing
    • AI-suggested links

  2. API-Reference (30 min reference)

    • REST API for all endpoints
    • Authentication endpoints
    • Project management
    • Memory CRUD operations
    • Search & context queries
    • Knowledge graph traversal
    • Repositories & webhooks
    • File attachments
    • AI sessions
    • Health & monitoring
    • Complete curl examples

For AI Integration (Claude, Cursor, Windsurf)

  1. MCP-Tools-Reference (25 min)
    • What is MCP and why it matters
    • Setup instructions (Claude Code, Cursor, Windsurf)
    • 30+ MCP tools reference
    • Tool descriptions & examples
    • Common workflows
    • Tool integration patterns
    • Best practices
    • Error handling
    • Debugging tips

Advanced & Specialized Topics

  1. Advanced-Topics (20 min)

    • Metadata repository sync (bidirectional)
    • Knowledge graph traversal deep dive
    • AI-suggested links
    • Batch operations
    • Workspace mapping for AI agents
    • Custom embedding models
    • Custom LLM models
    • Database sharding (large scale)
    • Webhook reliability
    • Multi-tenant setup
    • Custom authentication

  2. Troubleshooting-FAQ (reference)

    • Installation issues
    • Authentication problems
    • Git integration issues
    • Search problems
    • AI & Claude integration troubleshooting
    • Performance optimization
    • Webhook issues
    • LLM & embedding errors
    • FAQ (common questions)
    • Getting help & bug reports

🚀 Quick Start Paths

I just want to try Fold locally

  1. Read: Getting-Started → Option 1 (Docker)
  2. Follow the steps → You're running in 5 minutes
  3. Read: Overview-Concepts to understand what you have

I want to use Fold with Claude Code

  1. Get running: Getting-Started
  2. Connect a repo
  3. Read: MCP-Tools-Reference
  4. Use Fold from Claude Code

I'm setting up Fold for my team

  1. Read: Overview-Concepts — understand the benefits
  2. Setup: Getting-Started + Configuration
  3. Deploy: Deployment-Operations
  4. Integrate: MCP-Tools-Reference for your team's AI agents

I'm operating Fold in production

  1. Review: Deployment-Operations
  2. Reference: Configuration for all settings
  3. Monitor: Refer to Deployment section on observability
  4. Troubleshoot: Troubleshooting-FAQ
  5. Scale: Advanced-Topics for sharding/clustering

I'm building something with Fold's API

  1. Understand: Core-Concepts
  2. Reference: API-Reference
  3. Integrate: MCP-Tools-Reference if building AI features
  4. Advanced: Advanced-Topics for complex queries

📚 Documentation by Role

Product Managers / Team Leads

Backend Developers / Architects

DevOps / Infrastructure Engineers

AI / ML Engineers

Full-Stack Developers Using Fold

🎯 Common Tasks

"How do I start Fold?"

→ Getting-Started

"How do I connect Claude Code to Fold?"

→ MCP-Tools-Reference → Setup Instructions

"How do I index a new GitHub repository?"

→ Getting-Started → First Steps

"What are the authentication options?"

→ Configuration → Auth Providers

"How do I set up for production?"

→ Deployment-Operations

"How does semantic search work?"

→ Core-Concepts → Search & Retrieval

"What's the difference between memories?"

→ Core-Concepts → Memory Types

"Can I use Fold for multiple teams?"

→ Advanced-Topics → Multi-Tenant Setup

"Something's broken, help!"

→ Troubleshooting-FAQ

"How do I scale Fold?"

→ Deployment-Operations → Scaling

📖 Reading Order Recommendations

First time with Fold (30 min):

  1. Overview-Concepts — 15 min
  2. Getting-Started — 15 min

Getting productive (2 hours):

  1. Overview-Concepts
  2. Getting-Started
  3. Configuration (skim)
  4. MCP-Tools-Reference (if using with Claude)

Deep dive (4+ hours):

  1. Overview-Concepts
  2. Core-Concepts
  3. API-Reference
  4. MCP-Tools-Reference
  5. Configuration
  6. Deployment-Operations

Ops setup (3 hours):

  1. Getting-Started
  2. Configuration
  3. Deployment-Operations
  4. Troubleshooting-FAQ (bookmark)

💡 Key Concepts to Understand

  • Holographic Memory: Any fragment can reconstruct full context
  • Memories: Building blocks of knowledge (code, decisions, sessions, specs)
  • Knowledge Graph: Memories are linked by type (modifies, implements, causes, etc.)
  • Semantic Search: Find meaning, not keywords
  • Embeddings: Vector representations of text for similarity matching
  • Memory Decay: ACT-R inspired model where memory strength decays over time but is boosted by retrieval frequency - recent and frequently-accessed memories surface higher in search results
  • MCP: Protocol for AI agents to access Fold
  • Git Integration: Auto-index repos, webhooks keep memories in sync

🔗 External Resources

📝 Document Updates

These docs are maintained alongside the codebase. If you find:

  • Inaccuracies: Please open an issue
  • Missing information: Please suggest additions
  • Confusing explanations: Please let us know
  • Examples that don't work: Please report them

GitHub Issues: https://github.com/Generation-One/fold/issues

Clone this wiki locally