"Minigraf is not trying to replace Neo4j. It's trying to replace serde_json for graph data."

Minigraf aims to be the embedded graph memory layer for AI agents, mobile apps, and the browser — built on the SQLite philosophy: small, fast, reliable, zero-configuration, single-file.

Minigraf uses Datalog as its query language. Here's why it's the right choice:

Datalog is simpler → Aligns with "do less, do it perfectly":

• Datalog spec: ~50 pages of core concepts
• Smaller surface area = fewer bugs, faster to production

Datalog is proven → 40+ years of production use (Datomic since 2012, XTDB, LogicBlox) Datalog is reliable → Well-understood semantics, extensive research

Bi-temporal support was always the plan. Datalog makes it natural:

• Facts are tuples: (Entity, Attribute, Value, ValidFrom, ValidTo, TxTime)
• Time is just another dimension in relations
• Temporal queries use simple predicates: [(<= ?valid-from ?query-time)]
• No special temporal syntax needed - it's just data

Bi-temporal is 3-4 months of proven patterns (Datomic/XTDB model).

Recursive rules are first-class in Datalog:

[(reachable ?from ?to)
 [?from :connected ?to]]

[(reachable ?from ?to)
 [?from :connected ?intermediate]
 (reachable ?intermediate ?to)]

Transitive closure is native, not bolted on.

Datalog roadmap: 12-15 months to production (proven implementation patterns)

We can ship a useful, reliable database faster with Datalog.

Datalog space: Gap exists for single-file embedded bi-temporal DB

Minigraf = embedded graph memory for agents/mobile/browser + SQLite's simplicity + Datomic's temporal model (no one else offers this combination)

SQLite's success comes from a clear philosophy: be a library, not a server. Be small, not feature-complete. Be reliable, not cutting-edge. Minigraf adopts these same principles for graph databases.

Philosophy: It should just work, immediately, with no setup.

Implementation:

• No installation process beyond adding a dependency
• No server process to start or manage
• No configuration files to edit
• No connection strings or authentication for local use
• Minigraf::open("data.graph") and you're done

Anti-pattern: Requiring users to install external dependencies, start services, or edit config files.

Philosophy: Minigraf is a library you link against, not a server you connect to.

Implementation:

• In-process execution - direct function calls, no network overhead
• Runs in the same address space as your application
• No client-server architecture for embedded use
• Network protocols are opt-in extensions, not core features

Anti-pattern: Designing for client-server first and retrofitting embedded mode.

Target statement: "The graph database you compile into your app, not connect to."

Philosophy: All data in one portable file that's easy to manage.

Implementation:

• Single .graph file contains nodes, edges, properties, indexes, schema
• Easy to backup: copy one file
• Easy to share: email, USB drive, version control (for small DBs)
• Easy to delete: remove one file
• WASM: Store in browser's IndexedDB as single blob

Anti-pattern: Multiple files, directories, or complex file structures that are hard to manage.

Philosophy: Minimal dependencies. Small binary size. No external requirements.

Implementation:

• Pure Rust implementation
• Minimal dependency tree (currently: serde, uuid, anyhow)
• No required system libraries (optional backends OK)
• Target: <1MB binary for core engine
• No runtime dependencies (no JVM, no Python, no Node.js)

Anti-pattern: Requiring external services, libraries, or runtimes to function.

Philosophy: Run anywhere, from embedded devices to browsers to servers.

Implementation:

• Native: Linux, macOS, Windows, BSD, mobile
• WebAssembly: Run in any modern browser
• File format is endian-agnostic and cross-platform
• No platform-specific features in core (OS-specific optimizations OK)

Target platforms:

• Desktop: Windows, macOS, Linux
• Mobile: iOS, Android (via FFI/JNI)
• Web: WASM in browsers
• Embedded: Raspberry Pi, IoT devices
• Server: As a library in server applications

Anti-pattern: Platform-specific code in the core engine.

Philosophy: It's better to do less and do it perfectly than to do more and do it poorly.

Implementation:

• ACID transactions (Atomicity, Consistency, Isolation, Durability)
• Write-ahead logging (WAL) for crash recovery
• Data integrity checks on every operation
• Rigorous testing (aim for 100% branch coverage)
• Conservative feature addition
• No data loss, ever

Quality bar:

• Every feature must be fully tested
• Every feature must handle edge cases
• Every feature must be crash-safe
• Prefer proven algorithms over novel ones

Anti-pattern: Adding features before existing ones are bulletproof.

Philosophy: Your graph database files should work forever.

Implementation:

• Stable file format once v1.0 ships
• Can read graphs created 20+ years ago
• API stability: semantic versioning, no breaking changes in minor versions
• Clear migration paths when absolutely necessary
• Deprecation warnings 12+ months before removal

Commitment: Once v1.0 ships, file format is stable for decades.

Anti-pattern: Breaking changes, format churn, forced migrations.

Philosophy: Fast because simple, not simple because fast.

Implementation:

• Optimize the common case (small to medium graphs, <1M nodes)
• Page-based storage with locality of reference
• Indexes for frequently queried patterns
• Memory-mapped I/O where beneficial
• Avoid premature optimization

Target performance:

• Sub-millisecond queries for indexed lookups
• Thousands of transactions per second on commodity hardware
• Efficient memory usage (<100MB for medium graphs)

Anti-pattern: Complex optimization that sacrifices reliability or adds dependencies.

Philosophy: Documentation is as important as code.

Implementation:

• Every public API has rustdoc comments with examples
• Query language reference manual (like SQL reference)
• Architecture documentation for contributors
• Performance tuning guide
• Common patterns and recipes
• Migration guides between versions

Documentation types:

• API reference (generated from code)
• User guide (getting started, tutorials)
• Query language specification
• Internals guide (for contributors)

Anti-pattern: "The code is the documentation."

Philosophy: This is a marathon, not a sprint.

Implementation:

• Commitment to decades of support
• Conservative, deliberate feature additions
• No rewrites or "version 2.0" churn
• Security patches for old versions
• Focus on stability over novelty

Inspiration: SQLite has been maintained for 20+ years and is committed to 2050.

Anti-pattern: Framework churn, major rewrites, abandoned versions.

✅ An embedded graph database library

• Link it into your application like SQLite
• Direct function calls, no network overhead
• Runs in-process with your app

✅ A bi-temporal database

• Track when facts were recorded (transaction time)
• Track when facts were valid in the real world (valid time)
• Time travel queries: see any point in history
• Audit trails and compliance built-in

✅ A Datalog query engine

• Recursive rules for graph traversal
• Logic programming paradigm
• Simpler than SQL, more powerful for graphs
• Proven semantics (40+ years of research)

✅ A local-first storage solution

• Perfect for desktop applications
• Ideal for mobile apps
• Great for WASM in browsers
• Suitable for embedded devices

✅ A single-file graph store

• One .graph file, easy to manage
• Portable across platforms
• Simple backup and versioning

✅ A reliable, ACID-compliant database (Phase 5)

• Transactions with rollback support
• Crash recovery via WAL
• Data integrity guarantees

✅ A learning-friendly implementation

• Readable Rust code
• Well-documented internals
• Clear architecture

❌ Not a distributed database

• No clustering, no sharding, no replication
• Single-node only (by design)
• If you need distributed, use Neo4j or similar

❌ Not a graph analytics engine

• No built-in PageRank, community detection, etc.
• You can build these on top, or use external tools
• Focus is on storage and queries, not analytics

❌ Not a client-server system

• No network protocol in core
• No authentication/authorization layer
• No multi-user access control (use OS permissions)

❌ Not enterprise-focused

• No role-based access control (RBAC)
• No audit logging
• No high-availability features
• (These can be built on top if needed)

❌ Not trying to be Neo4j

• Different use case (embedded vs. server)
• Different scale (millions vs. billions of nodes)
• Different philosophy (library vs. service)

❌ Not chasing feature parity with XTDB/Datomic

• Simpler scope: single-file only
• No distributed features
• No vector search (separate crate if needed)
• Focus on reliability over features

Primary use cases (optimize for these):

1. Audit-heavy applications - Finance, healthcare, legal (bi-temporal = compliance)
2. Event sourcing - Full history, time travel debugging
3. Personal knowledge bases - Obsidian, Logseq, Roam-like apps with provenance
4. Mobile applications - Local graph storage on phones/tablets
5. Desktop applications - Apps that need relationship data (IDEs, note-taking, etc.)
6. Web applications (WASM) - Client-side graph storage in browsers
7. AI/RAG systems - Knowledge graphs with temporal provenance
8. Embedded devices - IoT, edge computing with graph data
9. Development/testing - Local graph database for testing
10. Small to medium production apps - Where embedded DB is sufficient

Secondary use cases (should work, but not optimized for):

11. Server applications - Using Minigraf as an embedded component
12. Data analysis - Exploring graph datasets locally
13. Education - Learning Datalog and temporal databases

Non-use cases (explicitly out of scope):

• Large-scale distributed systems
• Multi-datacenter replication
• Billion-node graphs
• Real-time analytics at scale

When evaluating a feature or design choice, ask:

• Would SQLite do this?
• Does it keep things simple and embedded?

• Can it cause data loss or corruption?
• Does it make the codebase harder to test?

• How many lines of code?
• How many new dependencies?
• Does it complicate the API?

• Is this needed for embedded/mobile/WASM?
• Or is it only useful for enterprise/distributed?

• Could this be an optional feature flag?
• Could this be a separate library on top of Minigraf?

• YES: Aligns with philosophy, improves reliability, serves primary use cases
• MAYBE: Useful but adds complexity, consider making optional
• NO: Violates philosophy, compromises reliability, or only serves non-use cases

You'll know Minigraf has succeeded when:

1. ✅ Ubiquity: Developers say "just use Minigraf" for embedded graph storage
2. ✅ Trust: Known for never losing data, crash-safe, reliable
3. ✅ Simplicity: New users are productive in under 5 minutes
4. ✅ Size: Core binary under 1MB, minimal dependencies
5. ✅ Portability: Runs everywhere from Raspberry Pi to browsers
6. ✅ Stability: API hasn't broken in years
7. ✅ Documentation: Comprehensive docs with examples
8. ✅ Longevity: Still maintained and improved 10+ years later

To maintain focus, these are explicitly NOT goals:

• ❌ Distributed consensus algorithms
• ❌ Multi-master replication
• ❌ Built-in authentication/authorization
• ❌ Competing with Neo4j/TigerGraph on their turf
• ❌ Real-time analytics (OLAP workloads)
• ❌ Graph visualization (provide data, let others visualize)
• ❌ Built-in ML/AI (provide APIs for external tools)

Inspired by SQLite's legendary testing rigor:

Test coverage goals:

• 100% branch coverage (aspirational)
• Property-based testing (quickcheck, proptest)
• Fuzz testing (cargo-fuzz)
• Fault injection (simulate disk errors, OOM)
• Memory safety (miri, valgrind)
• Cross-platform testing (CI on Linux, macOS, Windows)

Test-to-code ratio: Aim for 5:1 (5x more test code than library code)

Release criteria:

• All tests pass on all platforms
• No memory leaks detected
• No undefined behavior (miri clean)
• Performance benchmarks within 5% of baseline
• Documentation complete for new features

The .graph file format must be:

1. Stable - Once v1.0 ships, format is frozen for decades
2. Self-describing - Header with magic number and version
3. Portable - Endian-agnostic, cross-platform
4. Efficient - Page-based, locality of reference
5. Extensible - Can add features without breaking old readers
6. Verifiable - Checksums for integrity validation

1. Simple common case: db.add_node() should be one line
2. Safe by default: Require unsafe only where truly needed
3. Transactions explicit: Clear when you're in a transaction
4. Ergonomic errors: Result<T, Error> with helpful messages
5. Builder patterns: Complex operations use builders
6. Zero-cost abstractions: No runtime penalty for nice APIs

Phase 1: ✅ Prove the concept (COMPLETE)

• Basic graph model, simple queries, in-memory storage

Phase 2: ✅ Embeddability (COMPLETE)

• Single-file storage, persistent graph database, embedded API

Phase 3: ✅ Datalog Core (COMPLETE)

• EAV data model, basic facts and queries, recursive rules, semi-naive evaluation

Phase 4: ✅ Bi-temporal Support (COMPLETE - March 2026)

• Transaction time (tx_id, tx_count) + valid time (valid_from, valid_to)
• :as-of and :valid-at time travel queries, file format v2

Phase 5: ✅ ACID + WAL (COMPLETE)

• Write-ahead logging, transactions, crash recovery

Phase 6: ✅ Performance (COMPLETE — March 2026)

• Covering indexes (EAVT, AEVT, AVET, VAET), packed pages, LRU page cache, on-disk B+tree (file format v6), query optimizer

Phase 7: 🎯 Datalog Completeness (next — 6-8 weeks)

• Stratified negation (not / not-join), aggregation (count, sum, min, max), disjunction (or / or-join)
• ≥90% branch coverage target

Phase 8: 🎯 Cross-platform (3-4 months)

• WASM (browser via wasm-pack + npm; server-side via WASI)
• Mobile bindings (iOS .xcframework, Android .aar via UniFFI)
• Language bindings (Python, JavaScript, C)

Phase 9: 🎯 Ecosystem & Tooling (ongoing)

• Developer tools: database inspector, query profiler, time travel visualizer
• Documentation: Datalog language spec, cookbook, performance tuning guide
• Integration examples: GraphRAG pattern, LangChain/LlamaIndex agent memory, annotated end-to-end scenarios
• Ecosystem libraries: graph algorithms crate, schema validation, import/export, backup utilities
• Exploratory: database branching (db.branch() → independent .graph fork for speculative writes, agent sandboxing, test isolation)

v1.0.0: 9-12 months

See ROADMAP.md for detailed feature breakdown.

It's important to say "no" to preserve the project's focus:

Say NO to:

• Features that only serve enterprise/distributed use cases

• Complexity that compromises reliability

• Dependencies that increase binary size significantly

• Breaking changes without overwhelming justification

• Features that should be separate libraries

• Premature optimization

It's OK to say: "That's a great feature, but it's better suited for a library built on top of Minigraf."

Beyond SQLite, we draw inspiration from:

• Datomic: Immutable facts, temporal queries, Datalog
• XTDB: Bi-temporal database, time travel
• Cozo: Embedded Datalog, graph algorithms
• Redis: Simple, focused, well-documented
• Git: Single-file stores (packfiles), content-addressed storage
• DuckDB: Modern analytics, SQLite-style
• Local-first software: Offline-capable, user-owned data

Minigraf is a decades-long project. We optimize for:

• Reliability over features
• Simplicity over flexibility
• Longevity over hype
• Users over competitors

The goal is not to be the most feature-complete graph database. The goal is to be the one that's always there when you need it, works reliably, and never gets in your way.

Be boring. Be reliable. Be Minigraf.

This document is a living guide. When in doubt, refer back to these principles.