Alexandria Open Knowledge Graph
README.md
# Alexandria Open Knowledge Graph
The Alexandria Open Knowledge Graph is a read-only gateway into Alexandria's map of the great books. It speaks MCP (the Model Context Protocol, the standard way for AI agents to call tools), so any agent or program can search the books, open the debates they carry on, and trace ideas and thinkers through time.
Every answer links back to the exact passage in Alexandria's reader. Every machine-made link carries its evidence and the model checks that admitted it.
| | |
| --- | --- |
| Endpoint | `https://alexandria-kg-gateway-production.up.railway.app/mcp` |
| Get a key | [app.alexandria.wiki/open-kg](https://app.alexandria.wiki/open-kg) (free, reviewed by the team) |
| Documents | [`/docs`](https://alexandria-kg-gateway-production.up.railway.app/docs), and [`/llms.txt`](https://alexandria-kg-gateway-production.up.railway.app/llms.txt) for language models |
| Data licence | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Credit "Alexandria, Lightning Studios" (see [Licence](#licence-and-attribution)) |
| Code licence | Apache-2.0 ([LICENSE](LICENSE)) |
| Source | [github.com/Lightning-Learning-Studios/alexandria-kg](https://github.com/Lightning-Learning-Studios/alexandria-kg). Issues and suggestions are welcome there. |
| Version | 2.0.0 (November 19, 2026). See the [changelog](CHANGELOG.md) |
## Contents
- [Quickstart](#quickstart)
- [What the graph holds](#what-the-graph-holds)
- [The tools](#the-tools)
- [How the graph thinks](#how-the-graph-thinks)
- [Schema at a glance](#schema-at-a-glance)
- [Provenance](#provenance)
- [Ids and redirects](#ids-and-redirects)
- [Your own queries: explore and raw Cypher](#your-own-queries-explore-and-raw-cypher)
- [Keys, limits and errors](#keys-limits-and-errors)
- [Licence and attribution](#licence-and-attribution)
- [Privacy](#privacy)
- [Run it yourself](#run-it-yourself)
- [Settings](#settings)
- [Files](#files)
## Quickstart
### 1. Get a key
Request a free key at [app.alexandria.wiki/open-kg](https://app.alexandria.wiki/open-kg). Tell us what you want to build. A person reviews each request, and the key arrives by email.
### 2. Make one call with curl
The gateway is stateless, so one HTTP request is enough. This call checks a famous quotation against the library:
```bash
curl -s https://alexandria-kg-gateway-production.up.railway.app/mcp \
-H "x-api-key: $ALEXANDRIA_KG_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "find_quote", "arguments": {"quote": "The unexamined life is not worth living"}}}'
```
The answer names the book (Plato's *Apology*), the exact sentence (`apology_70_3`) and a link that opens the reader on that sentence.
### 3. Connect your agent
Claude Code:
```bash
claude mcp add --transport http alexandria-kg \
https://alexandria-kg-gateway-production.up.railway.app/mcp \
--header "x-api-key: YOUR_KEY"
```
Claude Desktop, through the `mcp-remote` bridge (add this to the Desktop config file, then restart Desktop):
```json
{
"mcpServers": {
"alexandria-kg": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://alexandria-kg-gateway-production.up.railway.app/mcp",
"--header", "Authorization:${ALEXANDRIA_KG_AUTH}"],
"env": { "ALEXANDRIA_KG_AUTH": "Bearer YOUR_KEY" }
}
}
}
```
Any other MCP client: point it at the endpoint and send the key in the `x-api-key` header or as a Bearer token. [The quickstart](docs/quickstart-mcp.md) has Cursor and Python examples.
### 4. Ask a real question
Give your agent a goal, not a script:
> *Using alexandria-kg, show me the strongest disagreement in the great books about whether lying is ever right. Give both sides with a passage each, and say which books stand where. Cite every passage with its link.*
The agent will reach for `search_debates`, then `get_debate`, and come back with positions, clashes and passages. More examples are in [the cookbook](docs/cookbook.md).
## What the graph holds
Counts are for the public graph on November 19, 2026, build `kg2-20261119-e2b5b3cd`. `get_graph_info` returns the current numbers.
| Layer | Count | What it is |
| --- | --- | --- |
| Books | 1,732 | The public library: works from about 1775 BCE to the present, each with a date, era, tradition and region. |
| Passages | 508,592 | Self-contained units of meaning, a few paragraphs each, embedded for meaning search. |
| Concepts | 27,209 | Ideas that recur across books, each with a definition and a guiding question. |
| Debates | 3,074 | Questions that many books answer, with their positions and clashes. |
| Great Ideas | 126 | Broad themes: 102 from Mortimer Adler's *Syntopicon*, 10 Eastern, 14 modern. |
| Topics | 1,309 | Subjects inside each Great Idea, such as "Guardian angels and fallen spirits" inside "Angel". 63,369 links place concepts and debates in them. |
| Served concept links | 6,351 | Reviewed links between concepts: 3,999 contradicts, 2,080 develops, 220 prerequisite, 52 resonates. |
| Canon | 802 and 11,440 | "Start here" picks for each Great Idea, and the ranks of each idea's 100 central works. |
| People | 41,082 | Authors (783 with books in the library) and the people the books discuss, with signed years. |
| Influence edges | 3,070 | Reviewed "A influenced B" edges between people, each with a tier of evidence and a topic. |
| Person-to-concept links | 9,635 | Reviewed links from a person to the concepts the books present them with, and how. |
| Learning corridors | 31,927 modules | Each book's ordered path through its ideas, anchored in verified quotes. |
| Entities | 2,697,726 | What each book's passages contain: arguments, tensions, characters, life challenges and more. |
## The tools
There are 31 tools. All are read-only. A 32nd, `run_cypher`, appears only when the operator switches raw Cypher on. Full details, with arguments and example answers, are in [docs/tools.md](docs/tools.md).
| Job | Tools |
| --- | --- |
| Find passages | `search_corpus` (by meaning), `find_quote` (an exact quote, to the sentence), `lookup_passage` (by id, sentence or reader link) |
| Books and people | `list_texts`, `get_text`, `search_people`, `get_person` |
| Concepts | `search_concepts`, `get_concept`, `get_concept_neighborhood` (served links with evidence), `get_concept_sources`, `get_concept_debates`, `list_domains` |
| Debates, Great Ideas and topics | `search_debates`, `get_debate`, `list_great_ideas`, `get_great_idea` (its canon and topics), `search_topics`, `get_topic` |
| Time | `trace_lineage` (concepts or people, by topic, in date order) |
| A person's question | `recommend_for_question` (Great Ideas, a canon reading list, debates, passages) |
| Inside one book | `search_entities`, `get_entity`, `get_related_entities`, `get_entities_in_passage`, `get_passages_for_entity`, `get_corridors_for_text`, `get_corridor` |
| Your own queries | `explore` (structured, inside the public graph), `run_cypher` (raw, when switched on) |
| The graph itself | `get_graph_info`, `resolve_ids` |
The gateway also offers its documents as MCP resources (`alexandria://docs/schema` and others) and 3 prompts: `study_a_debate`, `trace_an_idea` and `verify_a_quote`.
## How the graph thinks
**Passages are units of meaning.** The books are cut into passages that each hold one complete thought, so a search returns something you can quote. Each passage keeps the reader's sentence ids, so links open on the exact sentence.
**Concepts are cross-library.** A concept such as "The Social Contract" collects what many books say about one idea. A model wrote each concept's name and definition. Most are marked `provisional`, which means no person has reviewed the wording yet.
**Links are served only after review.** The pipeline proposed 28,738 links between concepts. Each served link passed three model checks: a classifier, an adversarial refuter and Jev (Lightning's scoring model). Only 6,351 links passed, and on November 19, 2026, Lightning removed the rest from the graph. The gateway serves only served links.
- `CONTRADICTS`: the two concepts answer the same question in opposite ways.
- `DEVELOPS`: the end concept builds on the start concept. Each link also says whether the books' dates agree (`time.order`).
- `PREREQUISITE`: the start concept is a logical step needed for the end concept. It is not a claim of influence.
- `RESONATES`: the two concepts echo each other without one developing the other.
**A debate is one question.** A debate (a "concept hub" in the graph) gathers the concepts that answer one question, such as "How, if at all, can a person atone for moral guilt?" Each answer is a *position*, graded `core` (it answers head on) or `case` (a worked example). A *clash* is a served contradiction between two concepts, and the gateway gives evidence for each side.
**Great Ideas carry a canon and topics.** Each Great Idea has a short "start here" list, in order, with a reason for each pick. It also ranks the library's 100 most central works for that idea, with the evidence behind each rank. Inside each Great Idea, topics gather the concepts and debates on one subject; a concept's `home` topic is the one it belongs to first.
**People live in time.** Years are signed: `-428` is 428 BCE. Each person's dates, era, tradition and region name their source (Wikidata, the graph, or a model). Influence edges are served only after review. Each has a tier (Wikidata, two independent sources, a citation, or a mention) and a topic status that says whether the library's passages establish what the influence was about. Person-to-concept links say which ideas the books present a person with, and how.
**Only the public library is visible.** A book is public when it has not been withdrawn and Alexandria's catalog lists it as in the library (status `ready`, `kg_processing` or `kg_complete`). Everything else follows from the books: a concept is public when a public book teaches it, and a topic when a public concept or debate is in it. Private client collections, books under review, deleted books and pilot layers never reach the named tools or `explore`.
## Schema at a glance
```text
Great Ideas (CanonicalConcept | ConceptHub | Topic) -[:PART_OF {role}]-> (GreatIdea)
(CanonicalConcept | ConceptHub) -[:IN_TOPIC {home}]-> (Topic)
(GreatIdea) -[:START_HERE {order, reason}]-> (Book)
(Book) -[:CANON_CENTRALITY {list_rank}]-> (GreatIdea)
Debates (CanonicalConcept) -[:FACET_OF {grade, role}]-> (ConceptHub)
(ConceptHub) -[:HUB_LEADS_TO]-> (ConceptHub)
Concept links (CanonicalConcept) -[:CANONICAL_REL {type, served}]-> (CanonicalConcept)
Teaching (CorridorModule) -[:INSTANCE_OF]-> (CanonicalConcept)
(CorridorModule) -[:ANCHORED_IN | COVERS_UNIT]-> (SemanticUnit)
(CorridorModule) -[:LEADS_TO]-> (CorridorModule)
Text (SemanticUnit) -[:BELONGS_TO]-> (Book) <-[:WROTE]- (Author)
(SemanticUnit) -[:NEXT | CITES_UNIT]-> (SemanticUnit)
Inside one book (Entity) -[:EXTRACTED_FROM]-> (SemanticUnit)
(Entity) -[:ADDRESSES | CONTRADICTS | DEVELOPS | EXEMPLIFIES]-> (Entity)
People and time (Entity) -[:REFERS_TO]-> (NamedEntity) -[:SAME_AS]-> (Author)
(NamedEntity) -[:INFLUENCED {served, topic}]-> (NamedEntity)
(NamedEntity) -[:ASSOCIATED_WITH {served, how_presented}]-> (CanonicalConcept)
```
Every label, link type and property, with the boundary rule for each, is in [docs/schema.md](docs/schema.md).
## Provenance
Every answer ends with a `provenance` block: the graph build id, the gateway and schema versions, the licence and a line to credit. Every served link also carries its own record:
| Field | Example | Meaning |
| --- | --- | --- |
| `gate` | classify: gemini-4-argon, CONTRADICTS, 0.9; refute: claude-sonnet-5-5, upheld, 0.72; Jev: claim, 0.9 | The checks that admitted the link. |
| `evidence` | passages labelled `u1`, `u2` and `side: start, end, both, context` | The passages the link's reasoning cites, in its own numbering. |
| `review` | change `relabel`, original type DEVELOPS, human approved | A later change by review, with its reason. |
| `run_id`, `prompt_version`, `prompt_sha256` | `x3-full-1`, `x3-proto-1` | Which build, prompt and run made the link. |
The build id (`kg2-<date>-<hash>`) changes whenever a public layer changes. Store it with results you save. [docs/provenance.md](docs/provenance.md) explains every field.
## Ids and redirects
Ids are stable. When two concepts or debates merge, the old id keeps working: tools follow it to the survivor and say so in a `redirect` field. A retired id without a public survivor, and any id outside the public graph, reports `not_found`, exactly like an id that never existed.
| Kind | Example |
| --- | --- |
| Book | `810eead8-c4eb-4903-98bc-ac2e987eea87` (or its slug, `The-Republic`) |
| Passage | `The-Republic_su_11` |
| Reader sentence | `republic_193_1` |
| Concept | `cc_7df87da24696b27ce320` |
| Debate | `hub_0e674865b82664f74989` |
| Great Idea | `justice` |
| Person | an author id, or a Wikidata-based id such as `wd:Q859` |
| Concept link | `rel_30672da871f9f0dde1b7aabb` |
`resolve_ids` checks up to 50 stored ids against the current build. Ids from version 1 of the gateway (the old graph) do not carry over.
## Your own queries: explore and raw Cypher
`explore` lets you write your own query over the public graph without writing Cypher text. You give a path pattern in Cypher's notation, conditions, columns, an order and a page. The gateway checks every label, link and property, adds the public rules for every node and link, and sends your values as parameters. The answer includes the Cypher that ran.
```json
{
"match": "(c:CanonicalConcept)-[r:CANONICAL_REL]->(o:CanonicalConcept)",
"where": {"r.type": "DEVELOPS", "r.pt_time_order": "forward", "c.domain": "power"},
"return_fields": ["c.name", "o.name", "r.edge_id", "r.score"],
"order_by": ["-r_score"],
"limit": 10
}
```
`explore` does not read the text a model wrote from a link's evidence (a link's summary, shared question, reasoning and quote) or a debate position's treatment. That text can come from a book outside the public library. The named tools return it when public evidence supports it.
`run_cypher` runs raw, read-only Cypher over the whole graph. It is switched off on the hosted gateway for now. When it is on, every query runs in a read-only transaction with a 10-second timeout, a cap of 100 rows and 1 MB, and the same rate limits. Raw Cypher reads the whole graph, including what the named tools leave out: pilot layers (labels that end in `Pilot`), retired concepts and debates, and books outside the public library. The gateway passes the public rules as parameters, so a raw query can keep to the public layer. [The cookbook](docs/cookbook.md#raw-cypher) shows how.
## Keys, limits and errors
These are the defaults. If your project needs more, say so when you request a key: Lightning can raise the limits for one key.
| Limit | Default | When you pass it |
| --- | --- | --- |
| Requests a minute, per key | 120, with bursts up to 40 | HTTP 429 `rate_limited`, with `Retry-After` |
| Requests a day, per key | 10,000 (resets at 00:00 UTC) | HTTP 429 `daily_quota` |
| Requests at once, per key | 4 | HTTP 429 `too_many_in_flight` |
| Requests with a missing or wrong key, per client address | 30 a minute | HTTP 429 for 1 minute |
| New keys checked, for all callers together | 5 a second | HTTP 429 `key_check_busy`; retry after 1 second |
| Rows per tool | 25 (100 for `explore` and `run_cypher`) | The answer is capped; page with `offset` |
| Query time | 10 seconds | Tool error `[timeout]` |
| `explore` and `resolve_ids` calls at once, for all keys together | 6 | Error `busy`; retry after 2 seconds |
| Request size | 256 KB | HTTP 413 |
Every answer to `/mcp` carries `RateLimit-Limit`, `RateLimit-Remaining` and `X-Daily-Remaining` headers.
Errors have stable codes. A bad argument comes back as a tool error whose text starts with the code in brackets, for example `[invalid_argument] direction must be both, upstream or downstream`. `explore` and `run_cypher` return an `error` object with `code` and `message`. Other codes: `unavailable` (the gateway cannot reach the graph or confirm which books are public, so it answers nothing), `embedding_unavailable` (meaning search is down; word-based tools still work), `raw_cypher_disabled`, `write_or_admin_refused`, `procedure_not_permitted`, and Neo4j's own codes for syntax errors in your queries.
## Licence and attribution
Lightning's derived data is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). That covers the concepts, links, debates, canon lists, people and dates, summaries, corridors and entities. You may copy, adapt and build on it, also commercially, if you credit the source. Copy this line:
> Data from the Alexandria Open Knowledge Graph by Alexandria, Lightning Studios (https://app.alexandria.wiki), licensed under CC BY 4.0.
Passage text is different. It keeps the licence of its source edition. Most books are in the public domain, but some editions are still in copyright. Quote passages as you would quote any book, and do not republish whole works.
The gateway's code is Apache-2.0.
The graph is a study aid, not an authority. Read [docs/disclaimer.md](docs/disclaimer.md) before you publish anything built on it.
## Privacy
The gateway serves no user data. It does not read Alexandria conversations, profiles, notes, highlights or reading history.
For each request the gateway logs the time, a non-secret key id, the tool name, the status and the duration. It never logs arguments: no questions, search words, quotes or queries. Your key's row in the key table records when the key was last used.
## Run it yourself
You need Python 3.11 or later. To run the tests, nothing else:
```bash
cd alexandria-kg
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
python -m pytest -q
```
To run the gateway against the graph, copy `.env.example` to `.env`, fill in the Neo4j, Supabase and DeepInfra settings, and start it:
```bash
alexandria-kg-gateway # MCP over standard input, for desktop clients
MCP_TRANSPORT=http uvicorn gateway.server:get_app --factory --port 8080 # HTTP
python tests/live_smoke.py # one call to every tool, against the real graph
```
## Settings
| Setting | Purpose |
| --- | --- |
| `NEO4J_ALEXANDRIA_V2_URI`, `_USERNAME`, `_PASSWORD`, `_DATABASE` | The knowledge graph (version 2). The gateway reads no other Neo4j settings. |
| `SUPABASE_URL`, `SUPABASE_ANON_KEY` | The catalog's `books` table (the public-book list) and the reader's sentences. |
| `SUPABASE_SERVICE_ROLE_KEY` | Key validation only, through one database function. |
| `DEEPINFRA_API_KEY` | Query embeddings (BGE-M3). |
| `GATEWAY_RAW_CYPHER` | `off` (default) or `on`. Keep it off while the graph holds data that is not public. |
| `GATEWAY_RATE_PER_MINUTE`, `GATEWAY_RATE_BURST`, `GATEWAY_DAILY_QUOTA`, `GATEWAY_MAX_IN_FLIGHT` | The default limits for every key: 120, 40, 10,000 and 4. |
| `GATEWAY_KEY_LIMITS` | Limits for particular keys, as JSON keyed by the key id the access log shows: `{"key:<id>": {"per_minute": 600, "daily_quota": 50000}}`. A malformed value stops the gateway from starting. |
| `GATEWAY_API_KEYS` | Static keys, comma-separated, for the operator's own tests. |
| `GATEWAY_GRAPH_BUILD_ID` | Optional fixed build id. Without it, the gateway computes one. |
- `/health` answers when the process is up. `/ready` answers 200 only when the gateway reaches a version 2 graph and has loaded the public-book list. Use `/ready` as the deploy health check, so a deploy with wrong settings never goes live.
- Run one replica: the rate limits live in memory.
- The public-book list refreshes about every 9 minutes, in the background. If a refresh fails, the last good list stays in use. If no list has ever loaded, the gateway answers nothing.
- Logs are JSON lines on standard output.
## Files
| File | What it does |
| --- | --- |
| `gateway/server.py` | MCP tools, resources and prompts; the HTTP app; keys, limits and the access log. |
| `gateway/boundary.py` | The public boundary: which books, concepts, debates, people and links are public. |
| `gateway/tools/` | The named tools, one module per layer. |
| `gateway/explore.py`, `gateway/public_schema.py` | The structured query compiler and the public schema it checks against. |
| `gateway/raw.py` | `run_cypher`, behind its switch. |
| `gateway/neo4j_client.py` | Read-only sessions, timeouts, row and size caps, the query guard. |
| `gateway/catalog.py` | Production reads: the books table and the reader's sentences. |
| `gateway/quotes.py` | Exact-quote matching. |
| `gateway/ratelimit.py` | Per-key limits. |
| `gateway/shape.py` | The public shape of passages, links and provenance. |
| `docs/` | The documents the gateway serves at `/docs`. |
| `tests/` | Offline tests, and `live_smoke.py` for the real graph. |
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues