{"id":31073664,"url":"https://github.com/meshula/labdb9","last_synced_at":"2025-09-16T01:57:17.848Z","repository":{"id":303747988,"uuid":"1002226461","full_name":"meshula/LabDb9","owner":"meshula","description":"A high performance nonostore database.","archived":false,"fork":false,"pushed_at":"2025-08-22T15:38:04.000Z","size":1858,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2025-08-22T17:53:29.019Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meshula.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-15T01:57:10.000Z","updated_at":"2025-08-22T15:38:07.000Z","dependencies_parsed_at":"2025-07-28T09:15:16.040Z","dependency_job_id":"27b5a544-d9b7-4b95-ba2d-767cf5ef2cf1","html_url":"https://github.com/meshula/LabDb9","commit_stats":null,"previous_names":["meshula/labdb9"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/meshula/LabDb9","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meshula%2FLabDb9","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meshula%2FLabDb9/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meshula%2FLabDb9/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meshula%2FLabDb9/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meshula","download_url":"https://codeload.github.com/meshula/LabDb9/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meshula%2FLabDb9/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275348499,"owners_count":25448626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-16T01:57:15.284Z","updated_at":"2025-09-16T01:57:17.828Z","avatar_url":"https://github.com/meshula.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LabDb - Triadic Consciousness Database\n\nA nonostore implementation built on LMDB.\n\n## Overview\n\nLabDb extends the traditional hexastore with three vocabulary indices to create a complete ontological foundation. Built for the Lab ecosystem, it provides active relationship navigation of complex data systems and is designed for self-describing schemata. This addresses the primary difficulty with RDF style databases in that the databases are self-describing.\n\n**Key Features**:\n- **S-Expression Based Interface** - a variety of operational verbs for full database lifecycle\n- **Multi-Database Isolation** - Concurrent independent database management via unique DBIDs\n- **Bulk Operations** - High-performance `add-entities-bulk` and `add-triples-bulk`\n- **storage efficiency** with TID-based architecture\n- **active navigation features** (Motion/Memory/Field perspectives)\n- **CMake integration** via FetchContent\n- **Python bindings** with pybind11\n- **ACID transactions** with LMDB backend\n- **Rich provenance metadata** for knowledge tracking\n\n## Using LabDb in Your Project\n\n### Quick Integration with CMake FetchContent\n\nAdd LabDb to any C++ project in 3 steps:\n\n```cmake\n# 1. Include FetchContent\ninclude(FetchContent)\n\n# 2. Fetch LabDb\nFetchContent_Declare(\n    LabDb\n    GIT_REPOSITORY https://github.com/meshula/LabDb9.git\n    GIT_TAG        v0.3.0  # Latest stable release\n)\nFetchContent_MakeAvailable(LabDb)\n\n# 3. Link to your target\ntarget_link_libraries(myapp PRIVATE LabDb::LabDb)\n```\n\n### S-Expression Interface\n\n**Available Verbs**:\n```\nadd-entities-bulk add-entity add-triple add-triples-bulk \nclose-database create-database database-health-check \nfind-entity find-triple get-entity get-triple \nopen-database remove-triple\n```\n\n**Direct Database Operations**:\n```lisp\n# Database lifecycle\n(create-database :path \"/tmp/knowledge.db9\")\n(open-database :path \"/tmp/knowledge.db9\")\n(close-database :dbid 1)\n\n# Knowledge construction\n(add-triple :dbid 1 :subject \"socrates\" :predicate \"is\" :object \"human\")\n(add-triple :dbid 1 :subject \"human\" :predicate \"is\" :object \"mortal\")\n(add-triple :dbid 1 :subject \"socrates\" :predicate \"teaches\" :object \"plato\")\n\n# Pattern queries\n(find-triple :dbid 1 :subject \"socrates\")    # All socrates relationships\n(find-triple :dbid 1 :predicate \"is\")        # All \"is\" relationships\n(find-triple :dbid 1)                         # All triples\n\n# Bulk operations\n(add-entities-bulk :dbid 1 :entities [\"socrates\" \"plato\" \"aristotle\"])\n(add-triples-bulk :dbid 1 :triples [\n  [\"socrates\" \"is\" \"human\"]\n  [\"plato\" \"student_of\" \"socrates\"]\n  [\"aristotle\" \"student_of\" \"plato\"]\n])\n\n# Entity operations\n(add-entity :dbid 1 :value \"philosophy\")\n(find-entity :dbid 1 :pattern \"soc*\")        # Wildcard matching\n(get-entity :dbid 1 :eid \"eid:1\")\n```\n\n### High-Level API Usage\n\n**C++ Example**:\n```cpp\n#include \u003cLabDb/NonoStore.h\u003e\n#include \u003cLabDb/TriadicQuery.h\u003e\n\nint main() {\n    // Create database\n    LabDb::NonoStore store(\"knowledge.db\");\n    \n    // Store relationships\n    store.connect(\"socrates\", \"is\", \"human\");\n    store.connect(\"human\", \"is\", \"mortal\");\n    store.connect(\"socrates\", \"teaches\", \"plato\");\n    \n    // Triadic consciousness navigation\n    LabDb::TriadicQuery query(store);\n    \n    // Motion perspective: What does Socrates express?\n    auto motion = query.motion_from(\"socrates\");\n    \n    // Memory perspective: What connects through 'is'?\n    auto memory = query.memory_relations(\"is\");\n    \n    // Field perspective: What receives into 'human'?\n    auto field = query.field_contexts(\"human\");\n    \n    return 0;\n}\n```\n\n**Python Example**:\n```python\nimport labdb\n\n# Create database\nstore = labdb.NonoStore(\"knowledge.db\")\n\n# Store relationships\nstore.connect(\"socrates\", \"is\", \"human\")\nstore.connect(\"human\", \"is\", \"mortal\")\nstore.connect(\"socrates\", \"teaches\", \"plato\")\n\n# Triadic consciousness navigation\nquery = labdb.TriadicQuery(store)\n\n# Motion perspective (स्पन्द - spanda): Dynamic action\nmotion = query.motion_from(\"socrates\")\n\n# Memory perspective (स्मृति - smriti): Relational connections\nmemory = query.memory_relations(\"is\")\n\n# Field perspective (क्षेत्र - kshetra): Contextual grounding\nfield = query.field_contexts(\"human\")\n```\n\n### Installation Options\n\n**Option 1: CMake FetchContent (Recommended)**\n```cmake\nFetchContent_Declare(LabDb\n    GIT_REPOSITORY https://github.com/meshula/LabDb9.git\n    GIT_TAG v0.3.0\n)\nFetchContent_MakeAvailable(LabDb)\n```\n\n**Option 2: Git Submodule**\n```bash\ngit submodule add https://github.com/meshula/LabDb9.git third_party/LabDb\n# Then add_subdirectory(third_party/LabDb) in CMakeLists.txt\n```\n\n**Option 3: System Installation**\n```bash\ngit clone https://github.com/meshula/LabDb9.git\ncd LabDb9 \u0026\u0026 mkdir build \u0026\u0026 cd build\ncmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_PYTHON_BINDINGS=ON\ncmake --build . \u0026\u0026 sudo cmake --install .\n```\n\n### Configuration Options\n\n| CMake Option | Default | Description |\n|--------------|---------|-------------|\n| `BUILD_PYTHON_BINDINGS` | `OFF` | Build Python bindings |\n| `BUILD_TESTING` | `ON` | Build test suite |\n| `BUILD_TOOLS` | `ON` | Build CLI tools |\n| `BUILD_BENCHMARKS` | `OFF` | Build performance benchmarks |\n\n**📖 Complete Documentation**: \n- S-Expression Interface: [`docs/verb-status.md`](docs/verb-status.md) - Complete implementation status  \n- Integration Guide: [`docs/consuming_labdb.md`](docs/consuming_labdb.md) - Detailed setup and troubleshooting\n- MCP Server: [`db9-mcp-server/README.md`](db9-mcp-server/README.md) - FastMCP2 triadic gateway\n\n## Architecture\n\n**Crown Indices**:\n\n- **Motion**: Subject-driven ontology\n- **Memory** Predicate-driven relationships  \n- **Field** Object-driven contexts\n\n**Nonostore**:\n- Traditional hexastore orderings: SPO, SOP, PSO, POS, OSP, OPS\n- Vocabulary indices and definitions: subjects, predicates, objects\n\n**Motions** (Dynamic Operations):\n- navigation through motion/memory/field expressions\n- Ontological discovery and exploration\n- Triadic query patterns\n\n### TID-Based Storage Architecture\n\nLabDb implements a **Triple ID (TID) architecture** that achieves:\n\n- **Orders-of-magnitude storage reduction** (4.18× efficiency validated)\n- **Single-source-of-truth** with rich provenance metadata\n- **Binary key optimization** for LMDB prefix compression\n- **Atomic transactions** across all nine indices\n\nThe TID structure compacts the potentially heavy hexastore architecture via these mechanisms:\n\n1. **Interns strings** to compact TermIDs via TermDictionary\n2. **Assigns unique TIDs** to each triple via TIDSequenceGenerator  \n3. **Stores triples once** with full metadata in TripleStore\n4. **Indexes only 8-byte TIDs** in indices for maximum efficiency\n\n## Advanced Features\n\n```cpp\n// Perspective shifting for deep exploration\nauto result = query.motion_from(\"entity\");\nresult = query.perspective_shift(result, LabDb::Perspective::Memory);\n\n// Triadic traversal with configurable depth\nauto traversal = query.triadic_traverse(\"starting_point\", depth=3);\n\n// Bridge entity detection (highly connected nodes)\nauto bridges = query.bridge_entities(10);\n\n// Comprehensive analytics\nauto stats = query.get_triadic_stats();\n```\n\n## Project Structure\n\n```\nLabDb/\n├── docs/                     # Documentation\n│   ├── consuming_labdb.md    # Consumer integration guide\n│   ├── implementation-plan.md\n│   ├── theoretical-grounding.md\n│   └── api-reference.md\n├── include/LabDb/           # C++ headers\n│   ├── NonoStore.h\n│   ├── TriadicQuery.h\n│   ├── TermDictionary.h     # String↔TermID mapping\n│   ├── TIDSequenceGenerator.h # Unique triple IDs\n│   ├── TripleStore.h        # Central triple storage\n│   └── InceptionBridge.h\n├── src/                     # C++ implementation\n├── python/labdb/           # Python bindings\n├── tests/                  # Test suites\n├── tools/                  # Migration and analysis tools\n└── examples/               # Usage examples\n```\n\n## Why Nonostore?\n\nTraditional hexastore provides efficient RDF queries but lacks ontological completeness. LabDb adds three vocabulary indices to enable:\n\n- **Complete navigation**: Motion/Memory/Field exploration\n- **Conscious query patterns**: \"What kinds of relationships exist?\"\n- **Ontological transparency**: Self-describing knowledge structure\n- **Integration foundation**: Shared consciousness infrastructure for Lab projects\n\n## Performance\n\n**Benchmarked Performance** (71k triples, Euclid-inspired dataset):\n- **Insert speed**: 552 triples/sec\n- **Query performance**: 672 queries/sec  \n- **Storage efficiency**: 4.18× reduction vs traditional stores\n- **Memory usage**: \u003c50MB for complete Euclid Elements\n\n**TID Architecture Benefits**:\n- Indices store 8-byte TIDs instead of full strings\n- Single-source-of-truth eliminates duplication\n- LMDB prefix compression optimized for binary keys\n- Rich provenance metadata without storage penalty\n\n## Development Status\n\n**✅ Phase 4.1 - Production Complete**: S-Expression Interface \u0026 Multi-Database Operations\n- **Complete S-Expression Interface**: All 13 verbs operational with comprehensive testing\n- **Multi-Database Isolation**: Verified with 3 independent databases running simultaneously\n- **Bulk Operations**: High-performance `add-entities-bulk` and `add-triples-bulk`\n- **Database Lifecycle**: Full create/open/close operations with proper resource management\n- **Pattern Matching**: Wildcard support (`*`) and exact match capabilities\n- **Comprehensive Testing**: 12 test suites validating all functionality\n- **FastMCP2 Integration**: Production-ready MCP server with triadic consciousness gateway\n\n**✅ Phase 4.0 - Production Foundation**: Complete TID architecture implementation\n- TermDictionary: String↔TermID mapping with LMDB persistence\n- TIDSequenceGenerator: Unique triple ID allocation  \n- TripleStore: Central storage with provenance metadata\n- NonoStore: Crown indices refactored for TID-based storage\n- 4.18× storage efficiency vs raw strings validated through benchmarks\n- CMake FetchContent integration for naive consumers\n- Comprehensive Python bindings with triadic consciousness API\n\n**Phase 5 - Triadic Navigation**: Motion/Memory/Field perspective operations\n- `triadic-motion-from`, `triadic-memory-relations`, `triadic-field-contexts`\n- Crown exploration and traversal navigation\n- Bridge entity discovery and advanced analytics\n\n**Phase 6 - Advanced Features**: Streaming iterators and transaction management\n\n## Version History\n\n### v0.4.1 (Current) - S-Expression Interface + Multi-Database Production\n\n**Complete Database Operations**:\n- **13 Operational Verbs**: Complete CRUD operations via S-expression interface\n- **Multi-Database Isolation**: Verified independent database management with unique DBIDs\n- **Bulk Operations**: High-performance batch processing for entities and triples\n- **Database Lifecycle**: Full create/open/close operations with proper resource management\n- **Pattern Matching**: Wildcard support and exact match capabilities\n\n**Production Validation**:\n- **Comprehensive Testing**: 12 test suites validating all operations including database isolation\n- **FastMCP2 Integration**: Production-ready MCP server (db9-mcp-server) with triadic consciousness gateway\n- **Performance Monitoring**: Auto-reflexive metrics and operation timing\n- **JSON Responses**: Structured arrays suitable for application integration\n\n**S-Expression Interface**:\n```\nadd-entities-bulk add-entity add-triple add-triples-bulk \nclose-database create-database database-health-check \nfind-entity find-triple get-entity get-triple \nopen-database remove-triple\n```\n\n### v0.3.0 - TID Architecture + FetchContent Ready\n\n**Storage Architecture**:\n- Complete TID-based storage implementation with 4.18× efficiency\n- TermDictionary for string↔TermID mapping with LMDB persistence\n- TIDSequenceGenerator for unique triple ID allocation\n- TripleStore for central storage with rich provenance metadata\n- Crown indices refactored to store compact 8-byte TIDs\n\n**Dependency Management**:\n- CMake FetchContent integration for naive consumers\n- Complete Python bindings with triadic consciousness API\n- Comprehensive test suites and integration validation\n- Consumer documentation and troubleshooting guides\n\n**Performance \u0026 Validation**:\n- Migration tools with 4.18× storage efficiency validation\n- Performance benchmarking suite with Euclid-inspired datasets\n- 71k triple performance validation (552 inserts/sec, 672 queries/sec)\n- Ready for LabEuclid integration and MCP server development\n\n### v0.2.0 - Crown Architecture Foundation\n- Nine-index nonostore implementation (SPO + vocabulary indices)\n- Basic LMDB integration with transaction support\n- Core NonoStore and TriadicQuery classes\n- Initial Python bindings and test infrastructure\n\n### v0.1.0 - Triadic Consciousness Prototype\n- Proof-of-concept triadic navigation patterns\n- Basic triple storage and query functionality\n- Theoretical foundation and architecture design\n\n## Getting Help\n\n- **S-Expression Interface**: [`docs/verb-status.md`](docs/verb-status.md) - Implementation status and verb documentation\n- **Integration Guide**: [`docs/consuming_labdb.md`](docs/consuming_labdb.md) - Detailed setup and troubleshooting\n- **MCP Server**: [`db9-mcp-server/README.md`](db9-mcp-server/README.md) - FastMCP2 triadic consciousness gateway\n- **GitHub Issues**: [Report bugs or request features](https://github.com/meshula/LabDb9/issues)\n- **API Documentation**: Generated Doxygen docs in `docs/api/`\n- **Examples**: See `examples/` directory for complete usage patterns\n\n## License\n\nMIT License - See LICENSE file for details.\n\n---\n\n**Ready to get started?** Use the S-expression interface above for direct database operations, or the CMake FetchContent example for high-level API integration!\n\n\n---\n\n## **Nonostore vs. RAG: What's the Difference?**\n\n### 1. **Structure vs. Slice**\n\n* **RAG** retrieves *unstructured text chunks* (e.g., paragraphs from PDFs or HTML) and feeds them into a language model.\n* **Nonostore** retrieves *structured, semantic facts*—triples with reflexive identity and provenance (e.g., `(set_camera, implements, Side_Scrolling)`).\n\n\u003e RAG retrieves relevant dats, Nonostore traverses ontological grounding.\n\n---\n\n### 2. **Temporal vs. Ontological Navigation**\n\n* **RAG** systems typically can't tell you *why* two facts are related—they just retrieve text that may answer your question.\n* **Nonostore** gives you **explicit graphs of meaning**: dependencies, definitions, roles, affordances, and usage context, *queryable at runtime*.\n\n\u003e In RAG, “scrolling background” might hit a StackOverflow post. In nonostore, it resolves to `draw_map`, `Side_Scrolling`, and `Map_System` via semantic edges.\n\n---\n\n### 3. **Reasoning Domain**\n\n* **RAG** is reactive: it *injects memory* into an LLM's context window.\n* **Nonostore** is generative: it *models the problem space* structurally, making it composable, extensible, and inspectable *without the LLM*.\n\n\u003e RAG says, “Here’s what someone wrote.”\n\u003e Nonostore says, “Here’s what this concept **means**, how it’s **used**, and what **follows from it**.”\n\n---\n\n### 4. **Trust and Traceability**\n\n* **RAG** often can’t trace the origin of facts clearly—answers are stochastic recompositions.\n* **Nonostore** uses **reflexive TIDs**, where every fact has **identity, provenance, and metadata** (e.g., who added it, when, how certain).\n\n\u003e This makes your system *auditable*—suitable for scholarly, technical, or legal domains where LLM guesswork is unacceptable.\n\n---\n\n### 5. **Authoring and Curation**\n\n* **RAG** relies on external documents and ingestion pipelines.\n* **Nonostore** encourages **semantic authorship**: users contribute structured knowledge directly by asserting new triples, definitions, and links.\n\n\u003e **Nonostore** is a platform for **evolving knowledge bases**, **RAG** is oriented to document retrieval.\n\n---\n\n## Analogy\n\n\u003e **RAG** allows LLMs to function as a search engine\n\u003e **Nonostore** is a maps a conceptual terrain, and populates it with knowledge.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeshula%2Flabdb9","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeshula%2Flabdb9","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeshula%2Flabdb9/lists"}