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