convez.ai
MCP Server
Alan-Jowett

LexonGraph

Alan-Jowett/LexonGraph

Ver no GitHub
InicialPluginScore · de 0 a 100

LexonGraph is a log-structured semantic index that stores embeddings as immutable blocks in navigable vector graph. It supports local and cloud backends, fast centroid-guided search, and efficient period rebuilds, enabling LLMs to retrieve precise context from large archival corpora.

Instalação

$npx convez-ai Alan-Jowett/LexonGraph

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
v0.1.0
Issues abertas
4
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

LexonGraph

CI Coverage Status License: MIT

LexonGraph is a semantic indexing and retrieval system built around immutable, content-addressed blocks. The repository now includes the canonical protocol documents, traceable specification packages, an implemented Rust workspace for the core repository surface, and CI that enforces the workspace quality gates.

Repository status

LexonGraph is still evolving, but the repository is no longer just an architecture sketch. It currently contains:

  • Active governed and implemented surface
    • canonical protocol documents for blocks, search, indexing, and DCBC
    • requirements/design/validation spec packages for the current Rust workspace and repository automation
    • implemented Rust crates for blocks, storage contracts, filesystem storage, deterministic clustering, indexing, search, and embedding-provider integration
  • Active repository maintenance surface
    • GitHub Actions CI for formatting, linting, tests, and coverage reporting
    • Dependabot configuration for Cargo and GitHub Actions dependency updates
    • repository maintenance skills under .github/skills/
  • Supporting, reference, and future-facing material
    • architecture notes, audits, and RCA documents under docs/arch/, docs/audits/, and docs/rca/
    • docs/protocol/ebcp.md as reference or future protocol work rather than part of the active governed implementation surface

The README is a summary. The protocol documents in docs/protocol/ and the traceable packages in docs/specs/ are the authoritative sources for protocol and specification behavior.

Architecture at a glance

  • Immutable blocks are encoded as canonical CBOR maps and addressed by sha256(canonical_cbor_bytes(block)).
  • Branch blocks point to child blocks, forming a Merkle-linked structure.
  • Leaf blocks carry embeddings, metadata, and inline content payloads.
  • Embedding providers are split between a provider-agnostic trait crate and concrete provider implementations.
  • Search uses deterministic frontier expansion over ranked candidates.
  • Indexing builds deterministic block sets from application-supplied items and uses DCBC-backed packing by default.
  • DCBC provides deterministic capacity-constrained balanced clustering for clustering and packing workflows.

Document map

AreaStatusDocument or pathPurpose
VisionSupportingdocs/vision.mdHigh-level architecture summary and design direction
Block protocolActive governeddocs/protocol/blocks.mdCanonical block encoding, invariants, and block identity
Search protocolActive governeddocs/protocol/search.mdDeterministic traversal, ranking, and termination semantics
Indexing protocolActive governeddocs/protocol/indexing.mdDeterministic index-construction inputs, invariants, and outputs
DCBC protocolActive governeddocs/protocol/dcbc.mdDeterministic capacity-constrained balanced clustering rules
EBCPReference / future-facingdocs/protocol/ebcp.mdEmbedding block compression protocol work that is not part of the active governed implementation surface in this pass
Architecture notesSupportingdocs/arch/Design explorations and deeper technical background
AuditsSupportingdocs/audits/Cross-artifact drift and traceability audit records
Root cause analysesSupportingdocs/rca/Focused follow-up analyses for specific drift or implementation issues

Specification packages

The repository uses spec packages under docs/specs/. Each package follows the same structure:

  • requirements.md for the required behavior and boundaries
  • design.md for the derived design
  • validation.md for the verification surface

Current packages cover:

  • repository-dependabot
  • rust-block-crate
  • rust-block-inspect-cli
  • rust-block-storage-trait
  • rust-dcbc-streaming-crate
  • rust-directional-pca-crate
  • rust-embeddings-openai-crate
  • rust-embeddings-trait
  • rust-filesystem-block-store
  • rust-pca-crate
  • rust-search-crate
  • rust-streaming-clustering-crate
  • rust-streaming-indexer-crate
  • rust-workspace-ci

Rust workspace

The top-level Cargo workspace currently contains:

CrateRole
lexongraph-blockTyped block model, validation, canonical CBOR serialization, and block-hash derivation
lexongraph-block-inspectCLI for inspecting canonical block encodings and decoded block structure
lexongraph-block-storeBackend-agnostic BlockStore trait plus conformance harnesses
lexongraph-block-store-fsLocal filesystem implementation of the block-store contract
lexongraph-dcbc-streamingDeterministic streaming DCBC clustering implementation
lexongraph-directional-pcaDeterministic directional PCA utilities for streaming clustering workflows
lexongraph-embeddings-traitShared async embedding-provider contract plus opt-in conformance helpers
lexongraph-embeddings-openaiOpenAI-compatible and Azure OpenAI embedding-provider implementation
lexongraph-pcaDeterministic, streaming-first PCA accumulation, affine transform algebra, and stable transform artifact encoding
lexongraph-searchProtocol-conforming search orchestration with trait-based policy hooks
lexongraph-streaming-clusteringShared streaming clustering contract plus conformance helpers
lexongraph-streaming-indexerProtocol-conforming streaming indexing orchestration with replay-based ingestion

At the moment, the implemented storage backend in this repository is the local filesystem block store. Broader deployment shapes remain part of the overall architecture direction rather than the current workspace implementation.

Contributor entrypoint

For Rust changes, use the same workspace commands enforced by CI:

cargo fmt --check --all
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked

The CI workflow lives in .github/workflows/ci.yml and currently runs on:

  • pushes to main
  • pull requests targeting main (filtered via paths: to repository-quality-relevant files including Rust workspace files, docs, hooks, .gitignore, .gitattributes, and workflow configuration)

The repository also defines .github/dependabot.yml for weekly Cargo and GitHub Actions dependency update proposals.

To enable the repository-managed local checks, configure Git to use the versioned hook directory:

git config core.hooksPath hooks

The pre-commit hook enforces SPDX headers on staged governed files, and CI re-checks the full tracked repository surface.

Repository maintenance skills live under .github/skills/ and support specification and maintenance workflows for this repository.

Repository layout

.
|- crates/
|  |- lexongraph-block
|  |- lexongraph-block-inspect
|  |- lexongraph-block-store
|  |- lexongraph-block-store-fs
|  |- lexongraph-dcbc-streaming
|  |- lexongraph-directional-pca
|  |- lexongraph-embeddings-openai
|  |- lexongraph-embeddings-trait
|  |- lexongraph-pca
|  |- lexongraph-search
|  |- lexongraph-streaming-clustering
|  `- lexongraph-streaming-indexer
|- docs/
|  |- arch/
|  |- audits/
|  |- protocol/
|  |- rca/
|  |- specs/
|  `- vision.md
|- .github/
|  |- dependabot.yml
|  |- skills/
|  `- workflows/ci.yml
|- hooks/
|- Cargo.toml
`- README.md

Current focus

The repository is centered on keeping the protocol surface, crate-level specs, and implemented Rust workspace aligned:

  • protocol-first definitions in docs/protocol/
  • traceable crate-level requirements in docs/specs/
  • verification-backed Rust implementations in crates/

License

MIT

Ver o original no GitHub

Bom para

Relacionados