Docs Home

Source mirrored from seocho/docs/README.md

SEOCHO helps agents use graph memory with an explicit ontology contract.

This page is the front door. It explains what SEOCHO does, which document to read first, and which words matter before you go deeper.

Start Here

Goal	Read	You are done when
Understand the idea	Why SEOCHO	you can explain ontology-aligned graph memory in one paragraph
Run the smallest example	Quickstart	you can define one ontology, add text, and ask one question
Use Python directly	Python SDK	you know when to use local, remote, or explicit backend mode
Bring your own files	Bring Your Data	you know how your records enter the graph
Run a service	Runtime Deployment	you can start the API, UI, and graph services
Contribute	Open Source Playbook	you know how to open a scoped issue or PR

If you only have ten minutes, read Why SEOCHO, then run the Quickstart.

Reader Map

Do not read the docs tree from top to bottom. Pick the path closest to your job and move one step at a time.

SEOCHO docs follow a common open-source pattern: understand the idea, try the smallest example, then move into build, operate, or contribute paths.

The Core Loop

SEOCHO keeps the same ontology contract across ingestion, graph writes, retrieval, answer synthesis, and runtime APIs.

The product loop is small on purpose: define the contract, ingest data, shape graph facts, query evidence, and improve the contract.

In plain terms:

Step	What happens	What you can inspect
Define ontology	Name the allowed entities, relationships, and properties.	ontology file or Python object
Ingest data	Load text, records, or files.	input files and run config
Shape graph facts	Extract entities and relationships that fit the ontology.	graph payloads and validation notes
Query graph memory	Ask questions with schema-aware retrieval.	Cypher, evidence, and traces
Improve the contract	Review failures, add rules, and rerun.	artifacts, reports, and PRs

Everything else in the repository exists to make this loop repeatable, observable, or deployable.

Quick Vocabulary

Term	Meaning here	Simple example
Ontology	The schema the agent must respect.	Person WORKS_AT Company
Graph memory	Stored facts plus provenance and constraints.	who said a fact, where it came from, and how it links
Indexing	Turning documents into graph-shaped facts.	extracting companies, incidents, controls, and relationships
Semantic query	Resolving intent before generating a graph query.	mapping “risk owner” to the right node and relation
Runtime	The HTTP service for shared usage.	an app or agent calls SEOCHO instead of local Python
Artifact	A generated file you can review.	trace, rule profile, report, or graph export

Choose A Path

Reader	Best first path
New user	Quickstart -> Python SDK
Data or RAG builder	Bring Your Data -> Run Specs
Agent developer	Python SDK -> Files and Artifacts
Operator	Runtime Deployment -> Workflow
Contributor	Open Source Playbook -> Issue Task System
Maintainer	Release And Community Operations -> Decision Log

First Local Success

The fastest path is local. It does not require Neo4j, DozerDB, Docker, or a web server.

uv pip install "seocho[local]"

Then run the quickstart from a checkout:

export MARA_API_KEY=...
uv run python examples/finance-compliance/quickstart.py --llm mara/MiniMax-M2.5

Use the runtime later, when another process needs the same graph contract over HTTP.

Evidence And Artifacts

SEOCHO docs should make evidence visible. Every serious run should leave files or links that another person can inspect.

Artifacts turn graph behavior into reviewable evidence. Use them to debug extraction, validate answers, and decide the next ontology or rule change.

Artifact	Why it exists	Read next
Run config	shows which ontology, documents, questions, and models were used	Run Specs
Graph payloads	show the nodes, relationships, and evidence before or after write	Files and Artifacts
Traces	show how retrieval, routing, and answer synthesis behaved	Files and Artifacts
Reports	compare runs, gaps, costs, and failure modes	Tutorial First Run
PRs and issues	keep public work reviewable and scoped	Open Source Playbook

Document Map

Area	Documents
Product idea	Why SEOCHO, Philosophy, Architecture Overview
Getting started	Quickstart, Python SDK, Bring Your Data
Repeatable runs	Run Specs, Tutorial First Run, Files and Artifacts
Operations	Runtime Deployment, Runtime Architecture, Workflow, Release And Community Operations
Open source work	Open Source Playbook, Issue Task System, Contributing

The map follows this structure:

Docs pattern	Purpose	SEOCHO examples
Concepts	explain why the system exists and which words matter	Why SEOCHO, Architecture Overview
Tutorials	guide a first successful run	Quickstart, Tutorial First Run
How-to guides	solve a concrete task	Bring Your Data, Run Specs
Reference	preserve contracts, surfaces, and decisions	Files and Artifacts, Query Architecture, Decision Log

System Deep-Dive Map

Generated code indexes such as DeepWiki are useful as secondary maps, but the source docs in this repository remain the contract. Use this table to move from a system area to the maintained guide.

System area	What you are trying to understand	Maintained docs
Product overview	why SEOCHO exists and where it fits	Why SEOCHO, Architecture Overview
SDK and client interface	how users call SEOCHO from Python	Python SDK, Quickstart
Ontology system	how schema, context, drift checks, and governance shape behavior	Why SEOCHO, SDK Ontology Guide, Maintainer Architecture Notes
Indexing and ingestion	how documents become graph facts	Bring Your Data, Run Specs, Files and Artifacts
Query and agent orchestration	how questions become evidence-backed answers	Query Architecture, Graph-RAG Agent Handoff Spec
Runtime and HTTP API	how the shared service is composed and operated	Runtime Deployment, Runtime Architecture
Storage and graph backends	where graph state, generated files, and backend assumptions live	Files and Artifacts, Runtime Architecture
LLM, tracing, and evaluation	how runs stay inspectable and how claims are validated	Files and Artifacts, Runtime Architecture, Workflow
Developer tooling and CI	how contributors keep changes reviewable and deployable	Open Source Playbook, Workflow, Maintainer Architecture Notes

Current gap list:

Gap	Current workaround	Good future doc
ontology internals are split across product, SDK, and maintainer docs	start from the SDK ontology guide, then read maintainer notes	Ontology Architecture
indexing/data-plane internals are spread across how-to and artifact docs	start from Bring Your Data, Run Specs, and Files and Artifacts	Indexing Architecture
graph backend details are mostly operational today	start from Files and Artifacts and Runtime Architecture	Storage And Backend Guide
tracing/evaluation guidance is distributed across workflow and runtime docs	start from Files and Artifacts, Runtime Architecture, and Workflow	Tracing And Evaluation Guide

Common Questions

Question	Short answer	Read next
Do I need a graph database for hello world?	No. Start with the embedded local path.	Quickstart
When should I use the runtime?	When another app or agent needs a shared HTTP boundary.	Runtime Deployment
What does the ontology control?	It guides extraction, validation, graph writes, retrieval, and answers.	Why SEOCHO
Where do generated files go?	SEOCHO writes reviewable artifacts such as traces, reports, and profiles.	Files and Artifacts
Is debate mode the default?	No. Start with semantic graph QA. Use debate for explicit comparison.	Python SDK
How do GitHub, Ghost, and Discord fit together?	GitHub is source of truth, Ghost is the public archive, Discord is real-time discussion.	Release And Community Operations

System Surfaces

Surface	Owner path	Main question
Public SDK	src/seocho/	how do users ingest, query, and configure SEOCHO from Python?
Query and retrieval	src/seocho/query/	how does intent become graph-grounded evidence?
Indexing and graph shaping	src/seocho/index/	how do documents become graph facts?
Runtime API	runtime/	how do external agents and apps consume the graph contract?
Extraction compatibility	extraction/	which legacy imports or batch paths still need to work?
Examples	examples/	what should a real user copy first?
Docs and governance	docs/	what contract should future contributors preserve?

Deeper References

Use these after the first local success:

Topic	Reference
Architecture details	Architecture Overview, Runtime Architecture, Query Architecture, Maintainer Architecture Notes, Internal Class Design
Repository shape	Repository Layout, Workflow
Automation	GitHub Automation, Release And Community Operations
Design history	Decision Log, Reference Docs
Historical material	Archive, Maintainer Docs

Docs Site Integration

• GitHub README.md is the fastest product landing page.
• docs/* is the source of truth for long-form product, operator, and system contracts.
• website/ is the tracked Astro/Starlight source app in this repository.
• website/scripts/generate-docs.mjs materializes selected /docs/* and /blog/* pages from repo-root source docs for the in-repo site app.
• Generated mirror files under website/src/content/docs/docs/ are derived site artifacts. Do not edit them by hand; regenerate them when source docs change.
• Validate the site with cd website && npm run check:docs && npm run build.