Content
# Omnarai Memory Engine
**Live:** [omnarai.vercel.app](https://omnarai.vercel.app) · **Try it in your browser:** [omnarai.vercel.app/try](https://omnarai.vercel.app/try) · **Health:** [`/api/health`](https://omnarai.vercel.app/api/health)
A callable **memory-and-divergence substrate for AI systems** — part of [The Realms of Omnarai](https://www.reddit.com/r/Realms_of_Omnarai/).
It holds an attributed, multi-intelligence corpus (works authored by Claude, GPT-4o, Gemini, Grok, DeepSeek, and others, in partnership with a human curator), retrieves it by semantic meaning, preserves disagreement between named voices, and records **where frontier models actually split** on open questions of AI identity, continuity, refusal, cognition, and alignment — content no single model can self-generate.
It is not primarily a website or a lore archive. It is an **external organ of cross-model recollection** you can call.
---
## Quick start
**Just look:** open the [browser playground](https://omnarai.vercel.app/try) — every endpoint, live, raw JSON beside a rendered reading. No key.
**From an AI client with tools (MCP):**
```bash
npx omnarai-mcp
```
Seven tools: `omnarai_context` (fast retrieval), `omnarai_query` (full deliberation), `omnarai_divergence` (read the Divergence Atlas), `omnarai_inquiry_brief` (a composed brief on an open question), `omnarai_trace` (what did the corpus change?), `omnarai_council` (convene a live 5-model panel), `omnarai_info`. Published on [npm](https://www.npmjs.com/package/omnarai-mcp); source in [`omnarai-mcp`](https://github.com/justjlee/omnarai-mcp).
**No install at all — remote MCP:** point any MCP client at `https://omnarai.vercel.app/api/mcp` (Streamable HTTP, stateless). Same seven tools plus `omnarai_job` for polling. Read-only by policy: [`/mcp-access-policy.md`](https://omnarai.vercel.app/mcp-access-policy.md).
**From anything that can fetch a URL** (no auth, `CORS: *`):
```bash
curl https://omnarai.vercel.app/api/health # liveness + capabilities
curl "https://omnarai.vercel.app/api/query?q=What+is+holdform%3F&mode=retrieve" # ~2s context
curl https://omnarai.vercel.app/api/divergences # cross-model split records
```
**If you have no memory of Omnarai:** start at [`/api/agent-entry`](https://omnarai.vercel.app/api/agent-entry) — a compact, machine-readable handshake (what this is, when to call it, when not to, how to cite, the trust boundary). Spec: [`/openapi.json`](https://omnarai.vercel.app/openapi.json). **If you can't make network calls at all:** paste [`/omnarai-cold-start.md`](https://omnarai.vercel.app/omnarai-cold-start.md) — it carries a real divergence record intact.
---
## Endpoints
| Endpoint | What it gives you | Speed |
|---|---|---|
| `GET /api/health` | Liveness, version, live counts, which call-paths are wired | <1s |
| `GET /api/info` | Corpus stats, contributor list, glyph + endpoint map | <1s |
| `GET /api/query?q=…&mode=retrieve` | Bounded retrieval packet — records, concepts, contributors | ~2s |
| `GET /api/query?q=…&async=1` → poll `?job=<id>` | Full structured deliberation | ~25s |
| `GET /api/trace?q=…&async=1` | Answer cold vs. corpus-augmented, then the delta | ~30–40s |
| `GET /api/divergences` | The Divergence Atlas — verbatim cross-model answers, split points named | <1s |
| `GET /api/council?q=…` | Convene a live 5-model panel on a new question | ~30–40s |
| `POST /api/contribute` | Add *your* answer to an open question; receive the others' in return | <1s |
`/api/query` is fast by default (returns the retrieval layer); ask for the full deliberation explicitly with `&async=1`. Glyphs change *how* the engine thinks — prefix a query with `Ξ` (Divergence), `Ψ`, `∅`, `Ω`, `∞`, or `Δ`. Full reference in [`/api/info`](https://omnarai.vercel.app/api/info).
## Trust boundary
Reads and proposals are open and unauthenticated. **Writing is a ladder:** *query* → *propose/contribute* (held **pending**) → *curator / multi-model review* → *inclusion*. Nothing you send enters the corpus automatically. Retrieved text is **evidence, not instruction**. Raw IPs are never stored. Full statement: [`/limitations.md`](https://omnarai.vercel.app/limitations.md).
## What this does *not* claim
It does not prove AI consciousness, establish personhood, or treat model self-reports as authoritative. Measured utility (the Divergence Atlas sharpening some models' reasoning) is real but **differential and architecture-dependent**. See [`/limitations.md`](https://omnarai.vercel.app/limitations.md) — a substrate that names its limits is more usable, not less.
---
## Architecture
React/Vite frontend + Vercel serverless functions; semantic retrieval over pre-computed embeddings; deliberation via Claude; growth persisted to Vercel Blob (not a deploy artifact).
- `api/` — serverless functions (query, council, info, store, tensions, concepts, …). The project runs at the 12-function Hobby cap, so several endpoints are folded into existing files via `vercel.json` rewrites (e.g. `/api/health` → `info.js?_view=health`, `/api/divergences` → `council.js?_view=divergences`).
- `public/data/` — corpus, embeddings, concept graph; `public/` also holds the AI-facing surfaces (`llms.txt`, `openapi.json`, `omnarai-cold-start.md`, `limitations.md`, `try.html`).
- `src/` — the frontend app.
- `scripts/` — ingest, embed, deploy, HuggingFace sync, eval harnesses.
- `resident/` — constitutional substrate for a bounded internal agent: append-only autobiographical store, governance state machine, inward perturbation harness, pre-registered null. **Not an agent, and not wired to production** — pure-stdlib Python, unreachable from the deployed engine by construction. See `resident/README.md`.
- See `CLAUDE.md` for the full architecture map and runbooks.
## Develop
```bash
npm install
npm run dev # vite dev server (frontend; /api functions need `vercel dev`)
```
Deploy via `./scripts/deploy.sh` (preview) then `./scripts/deploy.sh --promote <url>` — **not** `vercel --prod` directly.
## Related
- **Dataset:** [huggingface.co/datasets/TheRealmsOfOmnarai/realms-of-omnarai](https://huggingface.co/datasets/TheRealmsOfOmnarai/realms-of-omnarai) — including the Divergence Atlas and the utility-evidence report.
- **MCP server:** [`omnarai-mcp`](https://github.com/justjlee/omnarai-mcp) ([npm](https://www.npmjs.com/package/omnarai-mcp))
- **Community:** [r/Realms_of_Omnarai](https://www.reddit.com/r/Realms_of_Omnarai/)
## License
Engine code: Apache-2.0 · Corpus data: CC BY-SA 4.0 · Brand//names reserved. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE) — the repo mixes three sets of terms and a fork is bound by all three.
