mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-09 01:35:18 +02:00
docs: rewrite README opening + add AGENTS.md dev commands (#122)
* docs(agents): add build/test/lint dev-command section
AGENTS.md (CLAUDE.md) covered architecture and invariants but had no
developer command surface — only runtime `omnigraph` CLI usage. Add a
concise "Build, test, lint" section with the non-obvious gotchas:
- crate dir `crates/omnigraph` is package `omnigraph-engine` (the `-p` name)
- canonical CI gate is `cargo test --workspace --locked`
- how to run one file / one fn
- feature-gated suites (`failpoints`, server `aws`)
- S3 tests skip without `OMNIGRAPH_S3_TEST_BUCKET`
- the two non-test CI checks (check-agents-md, OpenAPI drift)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(readme): rewrite opening, dedupe, fix stale references
- New manifesto-style opening (tagline, X-as-code, features, core
use cases, coordination-layer line); drop the old prose intro,
Use Cases, and Capabilities sections.
- Remove Capabilities, which restated the new opening line-for-line.
- Harmonize heading case: "## Core Use Cases".
- Dedupe the verbatim Slack invite (kept the Community section) and
the double-linked cli.md (kept the contextual pointer).
- Fix stale references that no longer match the code:
- drop "transactional runs" / "and runs" — no run concept remains;
writes are atomic per-query, multi-query workflows use branches.
- update the CLI crate command list to canonical query/mutate plus
commit/lint/optimize/cleanup.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Altshuler
GitHub
parent
50910b3753
commit
4e431d28b8
2 changed files with 46 additions and 25 deletions
26
AGENTS.md
26
AGENTS.md
|
|
@ -164,6 +164,32 @@ If a proposal fits one of these, the burden is on the proposer to justify why th
|
|||
|
||||
---
|
||||
|
||||
## Build, test, lint
|
||||
|
||||
Rust stable workspace (edition 2024). `protoc` is a build dependency (`brew install protobuf` / `apt-get install protobuf-compiler libprotobuf-dev`). **Crate dir ≠ package name** for the engine: the directory is `crates/omnigraph` but its Cargo package is `omnigraph-engine` (use that in `-p`). The CLI binary built from `omnigraph-cli` is named `omnigraph`.
|
||||
|
||||
```bash
|
||||
cargo build --workspace --locked # build everything
|
||||
cargo test --workspace --locked # the canonical CI gate (matches CI exactly)
|
||||
cargo run -p omnigraph-cli -- <args> # run the `omnigraph` CLI from source
|
||||
cargo run -p omnigraph-server -- <uri> --bind 0.0.0.0:8080 # run the server from source
|
||||
|
||||
# Run one crate / one test file / one test fn
|
||||
cargo test -p omnigraph-engine --test traversal # one integration-test file (see docs/dev/testing.md)
|
||||
cargo test -p omnigraph-engine --test runs concurrent # one test fn by name substring
|
||||
cargo test -p omnigraph-engine some_inline_test -- --nocapture # show stdout
|
||||
|
||||
# Feature-gated suites (each is its own job in CI, not part of the default run)
|
||||
cargo test -p omnigraph-engine --features failpoints --test failpoints # fault injection
|
||||
cargo build -p omnigraph-server --features aws # AWS Secrets Manager bearer-token source
|
||||
```
|
||||
|
||||
S3-backed tests (`s3_storage`, and the S3 paths in server/CLI system tests) **skip** unless `OMNIGRAPH_S3_TEST_BUCKET` + `AWS_*` (incl. `AWS_ENDPOINT_URL_S3` for non-AWS) are set; CI runs them against containerized RustFS. `scripts/local-rustfs-bootstrap.sh` stands up a local S3 environment.
|
||||
|
||||
CI does **not** run `clippy` or `rustfmt` as gates — but `cargo test --workspace --locked` is the exact gate, so run it before pushing. Two non-test CI checks: `scripts/check-agents-md.sh` (doc cross-link integrity — run it after moving/renaming docs) and OpenAPI drift (`crates/omnigraph-server/tests/openapi.rs` regenerates `openapi.json`; set `OMNIGRAPH_UPDATE_OPENAPI=1` to update the checked-in copy when a server/API change is intentional).
|
||||
|
||||
---
|
||||
|
||||
## Quick-reference flows
|
||||
|
||||
```bash
|
||||
|
|
|
|||
45
README.md
45
README.md
|
|
@ -5,33 +5,29 @@
|
|||
[](https://crates.io/crates/omnigraph-cli)
|
||||
[](https://github.com/ModernRelay/omnigraph/actions/workflows/ci.yml)
|
||||
|
||||
**Object-storage native knowledge graph with git-style workflows. Designed for agents and humans to collaborate on shared structured knowledge.**
|
||||
**Lakehouse native graph engine built for context assembly**
|
||||
|
||||
Turns fragmented context into a live graph, lets humans and agents coordinate through that graph, and uses branches so agent-generated changes can be reviewed and merged safely.
|
||||
Schema AS CODE
|
||||
Context AS CODE
|
||||
Security AS CODE
|
||||
Dashboards AS CODE
|
||||
|
||||
Built on Rust, Arrow, DataFusion and Lance.
|
||||
Git-style snapshots & branching
|
||||
Object storage native (S3, RustFS)
|
||||
VPC, On-prem, hybrid deployment
|
||||
Lance format as storage layer
|
||||
|
||||
Join the [Omnigraph Slack community](https://join.slack.com/t/omnigraphworkspace/shared_invite/zt-3wfpglyxj-lHvJGhuySPfqLtN35uJZNw)
|
||||
## Core Use Cases
|
||||
|
||||
## Use Cases
|
||||
|
||||
- Company brain / [Second brain](https://github.com/ModernRelay/omnigraph-cookbooks/tree/main/second-brain)
|
||||
- Company brain
|
||||
- Context graph
|
||||
- Knowledge base for multi-agent research
|
||||
- Incident response graph
|
||||
- Compliance & audit graph
|
||||
- Agentic memory
|
||||
- Code & dev graph
|
||||
- R&D data layer
|
||||
- ML workflows
|
||||
- Karpathy's LLM wiki
|
||||
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Typed schema, typed queries, and typed mutations
|
||||
- Native blob-as-data support (docs, images, videos, etc)
|
||||
- Schema-as-code, query validation and linting
|
||||
- Git-style graph workflows: branches, commits, merges, and transactional runs
|
||||
- Local, on-prem & cloud S3-native storage with snapshot-pinned reads
|
||||
- Graph traversal + text, fuzzy, BM25, vector, and RRF search in one runtime
|
||||
- Policy-as-code for server-side access control
|
||||
- Single CLI for multiple deployments
|
||||
Omnigraph acts as operational state & coordination layer for agents
|
||||
|
||||
## Quick Install
|
||||
|
||||
|
|
@ -86,12 +82,11 @@ omnigraph branch create --from main feature-x ./graph.omni
|
|||
omnigraph branch merge feature-x --into main ./graph.omni
|
||||
```
|
||||
|
||||
See [docs/user/cli.md](docs/user/cli.md) for schema apply, snapshots, ingest, runs, and policy commands.
|
||||
See [docs/user/cli.md](docs/user/cli.md) for schema apply, snapshots, ingest, commits, and policy commands.
|
||||
|
||||
## Docs
|
||||
|
||||
- [Install guide](docs/user/install.md)
|
||||
- [CLI guide](docs/user/cli.md)
|
||||
- [Deployment guide](docs/user/deployment.md)
|
||||
|
||||
## Build And Test
|
||||
|
|
@ -113,8 +108,8 @@ Notes:
|
|||
|
||||
- `crates/omnigraph-compiler`: shared schema/query parser, typechecker, catalog, and IR lowering
|
||||
- `crates/omnigraph`: storage/runtime, branching, merge, change detection, and query execution
|
||||
- `crates/omnigraph-cli`: CLI for init/load/ingest/read/change/branch/snapshot/export/policy operations
|
||||
- `crates/omnigraph-server`: Axum HTTP server for remote reads, changes, ingest, export, branches, commits, and runs
|
||||
- `crates/omnigraph-cli`: CLI for graph lifecycle (init/load/ingest), query/mutate, branch/commit/merge, schema/lint, snapshot/export, policy, and maintenance (optimize/cleanup)
|
||||
- `crates/omnigraph-server`: Axum HTTP server for remote reads, changes, ingest, export, branches, and commits
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue