[← Home]

####  ##### #   #
#   # #     #   #
#   # ###   #   #
#   # #      # #
####  #####   #

Developer Guide

FoldDB is a personal database that uses AI to automatically organize your data. Drop in files, JSON, or social media exports — FoldDB detects schemas, extracts searchable keywords, and lets you query with natural language.

----------------------------------------------------------------------------------------------------------------------------------------

QUICK START Up and running in minutes

1. INSTALL

curl -fsSL https://raw.githubusercontent.com/shiba4life/fold_db/master/install.sh | sh

Auto-detects macOS (Apple Silicon / Intel) and Linux x86_64

Or from source:

cargo install --git https://github.com/shiba4life/fold_db.git --bin folddb

2. CONFIGURE

export FOLD_OPENROUTER_API_KEY="sk-..."

Required for AI-powered ingestion and natural language queries

3. RUN

./run.sh --local

Web UI at localhost:5173 · Backend at port 9001

./run.sh --local --local-schema  # Fully offline
./run.sh --local --empty-db      # Fresh database
./run.sh --local --dev           # Dev schema service

HOW IT WORKS The ingestion-to-query pipeline

Files / JSON / APIs
       |
       v
  AI Ingestion -----> Schema Service (detects or creates schema)
       |
       v
  Mutation ----------> Storage (Sled local or DynamoDB cloud)
       |
       v
  Keyword Indexing --> AI extracts and normalizes searchable terms
       |
       v
  Query -------------> Natural language or structured field queries

INGEST

Send data in any format. AI analyzes the structure and maps it to a schema automatically.

SCHEMA

The global schema service at schema.folddb.com checks for existing compatible schemas or creates new ones.

STORE

Data is written as mutations with AES-256-GCM encryption at rest. Local keys or AWS KMS.

INDEX

AI extracts keywords and normalizes terms (dates, names, etc.) for search.

QUERY

Search with natural language or structured field queries. Schema-aware planning for efficient retrieval.

PERMISSIONS

Trust-based access control at the field level. Multi-tenant isolation enforced at the storage layer.

CODE EXAMPLES Rust and TypeScript APIs

RUST — AI INGESTION

use fold_db::{IngestionConfig, IngestionCore, IngestionRequest};
use serde_json::json;

let config = IngestionConfig::from_env_allow_empty();
let ingestion = IngestionCore::new(config)?;

let data = json!({
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30
});

let result = ingestion.process_json_ingestion(
    IngestionRequest { data }
).await?;

RUST — NATURAL LANGUAGE QUERY

use fold_db::FoldNode;

let node = FoldNode::new_with_defaults().await?;

// Natural language query
let response = node.ai_query(
    "Show me all purchases over $50"
).await?;

RUST — SERVERLESS (LAMBDA + DYNAMODB)

use fold_db::lambda::{
    LambdaConfig, LambdaContext,
    LambdaStorage, LambdaLogging
};
use fold_db::storage::{DynamoDbConfig, ExplicitTables};

let config = LambdaConfig::new(
    LambdaStorage::DynamoDb(DynamoDbConfig {
        region: "us-east-1".to_string(),
        tables: ExplicitTables::from_prefix("MyApp"),
        auto_create: true,
        user_id: None,
    }),
    LambdaLogging::Stdout,
);

LambdaContext::init(config).await?;
// Creates 11 DynamoDB tables with multi-tenant isolation

TYPESCRIPT — FRONTEND CLIENTS

import {
  schemaClient,
  securityClient,
  systemClient
} from "../api/clients";

// Schema operations with automatic caching
const response = await schemaClient.getSchemas();
if (response.success) {
  const schemas = response.data; // Fully typed
}

// System monitoring with 30-second cache
const status = await systemClient.getSystemStatus();

Available clients: SchemaClient · SecurityClient · SystemClient · TransformClient · IngestionClient · MutationClient

CLI REFERENCE folddb command line

STATUS & SCHEMAS

folddb status -p                       # Node health
folddb schema list -p                  # List all schemas
folddb schema load schema.json         # Load a schema
folddb schema approve my_schema        # Approve pending
folddb schema get my_schema -p         # Inspect schema

INGEST

folddb ingest run data.json            # Ingest JSON file
folddb ingest smart-folder ~/Documents --scan
                                       # Scan a directory
folddb ingest smart-folder ~/Documents --all-recommended
                                       # Batch ingest

QUERY

folddb query run tweets --fields text,author
                                       # Structured query
folddb query search "machine learning" # Full-text search
folddb query ai "recent purchases"     # Natural language

DEVELOPMENT

git clone https://github.com/shiba4life/fold_db
cd fold_db
cargo build --release --workspace
cargo test --workspace
cargo build --features ts-bindings     # TS bindings

CONFIGURATION Environment variables

VARIABLE                         PURPOSE
─────────────────────────────────────────────────────────────────
FOLD_OPENROUTER_API_KEY          API key for AI ingestion
DATAFOLD_SCHEMA_SERVICE_URL      Schema service (default: schema.folddb.com)
DATAFOLD_CONFIG                  Path to config file
DATAFOLD_LOG_LEVEL               trace | debug | info | warn | error
DATAFOLD_STORAGE_MODE            Storage backend ("s3" for cloud)
DATAFOLD_S3_BUCKET               S3 bucket for database storage
DATAFOLD_S3_REGION               AWS region for S3
DATAFOLD_UPLOAD_STORAGE_MODE     Upload storage ("s3" for cloud)

SCHEMA REGISTRY Live from schema.folddb.com

Browse the global schema registry. Schemas define data structure, permissions, and topology for interoperability across nodes. During ingestion, AI checks this registry for compatible schemas before creating new ones.

schemas | total fields | service: checking...

Loading schemas from registry...

DOCUMENTATION Deeper reading

API REFERENCE

Complete Rust API docs on docs.rs/fold_db

INGESTION GUIDE

AI-powered data ingestion — INGESTION_README.md

AI QUERY GUIDE

Natural language queries — AI_QUERY_USAGE_GUIDE.md

ARCHITECTURE

System design and patterns — Unified_Architecture.md

----------------------------------------------------------------------------------------------------------------------------------------

folddb v0.1.0 Dual-licensed MIT / Apache 2.0
PROJECT GitHub GOAL.md docs.rs
LINKS Schema Registry Issues Discussions
© 2025 Fold DB — Built in the open