One graph engine, two write paths.
A queryable knowledge base over your documents, and an agentic memory layer for Claude Code, Codex, and OpenCode.
One library. Two ways to use it.
The same engine powers two distinct use cases on the same artefacts. Pick where to start.
Ask your documents
Point GRAIL at a folder of PDFs, markdown, or code. Index once, query through six search modes — including an agent that picks the right tool for each question.
KB quickstart →Give your agent memory
Persistent memory for your agents in Claude Code, Codex, or OpenCode. The agent declares entities and relationships directly — no intermediate LLM extraction step. Available as a Python SDK or as a ready-made skill for your framework.
Learn
Core concepts
Build intuition before the technical details. Each page starts with an analogy, then the mental model, then the technicals.
What is GRAIL?
The library, the librarian, and the graph. The core idea in five minutes.
→The two modes
Knowledge base vs agentic memory, side by side. When to pick which.
→The six search modes
One tool per question. When to use local, cascade, global, document, agent, recall.
→Cascade in depth
Why cascade wins on factual questions. How it combines graph with text rescue.
→Memory model
How GRAIL thinks about agent memory: typed observations, folders as communities, consolidate proposals.
→Honest cost tracking
Why you'll never see a fake $0.00. How to budget before you index.
→Get started
Five minutes to your first answer
Step-by-step recipes to get going. Pick by use case.
Install GRAIL
uv or pip · Python 3.12 · 11 LLM endpoints built in · .env ready.
→KB quickstart
From zero to your first query on your own PDFs. Index, ask, chat.
→Memory quickstart
Create a memory project, write your first observation, query with recall.
→Skill quickstart
Install the skill in Claude Code, Codex, or OpenCode. Persistent memory for your agent.
→More resources
When you're deeper in
Task-oriented guides, full technical reference, and end-to-end copy-paste projects.
Guides
How to optimise costs, trace queries for debug, visualise the graph. Concrete recipes for common tasks.
→CLI reference
Every grail subcommand with flags and examples. The page you open when you forget a parameter.
→Python SDK
The GRAIL and MemoryProject classes. The API the CLI wraps. For embedding GRAIL in your own app.
→Cookbook
Complete copy-paste projects. PDF Q&A bot, multi-tenant memory, and more in development.
→
Acknowledgements
Standing on others' shoulders
Technical inspiration
The single-pass LLM extraction of entities and relationships from text chunks in GRAIL's knowledge-base mode draws inspiration from Microsoft GraphRAG. Everything else — incremental updates, cascade retrieval, the agentic search loop, the agentic memory mode and its proposal-based consolidation, recall mode, typed relationships, retrieval queries on entities, honest cost tracking, file-level provenance, and the dual-write-path architecture — is GRAIL's own design.
Commission
GRAIL is developed under the open-source commission of the Cámara Chilena de Inteligencia Artificial. Author and creator: Benjamín González Guerrero, founder of Nirvai.
NirvaiVisit Nirvai →