krail 0.2.2

Local-first memory and workflows for serious AI agent projects

KRAIL

KRAIL is a local-first, repo-backed knowledge runtime for projects where agents need durable context, not just chat history. It gives a project folder a repeatable structure for captures, topic pages, source dependencies, lightweight graphs, vector search, evidence-backed synthesis, workflow tasks, and integrity records.

The PyPI distribution is named krail. The Python import namespace remains rail for compatibility with earlier RAIL/KRAIL code.

pip install krail

import rail

project = rail.local("./my-knowledge-project")
print(project.doctor())

Documentation And DeepWiki

For a browsable, code-indexed guide to the full repository, use the generated DeepWiki:

https://deepwiki.com/AkeBoss-tech/knowledge

DeepWiki is useful when you want to understand how the pieces of KRAIL fit together beyond the package-level quick start. It indexes the repository and organizes the codebase into guided sections such as:

• Overview and local-first philosophy
• Getting Started
• Repository layout and package structure
• Core concepts and data model
• The rail.yaml project manifest
• Project lifecycle phases
• Research integrity and provenance
• Knowledge packs and project templates
• rail-py SDK and CLI
• KnowledgeRuntime and the krail CLI
• Markdown graph engine
• Vector store and hybrid search
• Hydration engine and pipeline runner
• Autonomous agent system
• Planner runtime and brief ingestion
• Runner infrastructure and session lifecycle
• API layer and endpoint groups
• MCP server, tool reference, and deployment
• CI/CD workflows, testing strategy, and local development

Use this README when you need the package install path and day-one workflows. Use DeepWiki when you want to navigate the implementation, trace a feature to the source files, or understand the broader monorepo architecture.

Why KRAIL?

Most retrieval tools stop at "here are the matching documents." KRAIL is built around a fuller project loop:

capture -> promote -> search -> think -> dispatch -> verify -> preserve

Use KRAIL when you want a local knowledge workspace that can:

• capture raw notes, files, URLs, and stdin into a predictable inbox
• promote useful captures into stable topic pages
• keep project knowledge in ordinary repo-backed markdown and YAML files
• build a markdown-frontmatter graph of topics, entities, claims, and links
• search local evidence deterministically
• build a local SQLite vector index for RAG-style retrieval
• synthesize answers with citations, gaps, conflicts, and next actions
• manage repo-backed tasks, work orders, workflows, and session records
• run local CLI agents such as Codex, Claude Code, Gemini, Cursor, or Copilot
• track source freshness, affected documents, claims, assumptions, and artifacts
• expose the same local project to MCP-compatible agent clients

KRAIL is intentionally headless. It does not require a hosted database, SaaS control plane, frontend, or remote runner. A project folder plus the CLI is the source of truth.

Install

KRAIL requires Python 3.11 or newer.

pip install krail

Optional extras:

pip install "krail[local]"
pip install "krail[analysis]"
pip install "krail[embeddings]"

The extras enable heavier local capabilities:

• local: ontology and DuckDB helpers
• analysis: numerical and plotting dependencies
• embeddings: sentence-transformer embedding support

After installation, both commands point to the same CLI:

krail --version
rail --version

krail is the preferred command name. rail remains available for compatibility.

Quick Start

Create a new local knowledge project:

krail init robotics-kb --pack research-intelligence --mode markdown_graph
cd robotics-kb
krail --local doctor

Capture raw material:

krail --local capture "GCS may be useful as a feasibility layer for task plans"
krail --local capture --file ./paper-notes/gcs.md --type paper-note
echo "quick thought from stdin" | krail --local capture --stdin

Review the inbox:

krail --local inbox list

Promote useful material into durable topic pages:

krail --local inbox promote topics/inbox/<capture>.md \
  --topic task-and-motion-planning \
  --type method

krail --local topic upsert task-and-motion-planning \
  --content "Reviewed update with evidence."

Search local evidence:

krail --local search "GCS feasibility" --explain

Find typed records across documents, graph entities, integrity records, artifacts, workflow sessions, and ingestion queues:

krail --local find "repo intake" --type workflow_run --status failed --json

Inspect permission metadata. Existing projects are public by default; records become restricted only when they opt in with metadata such as visibility: private, allowed_roles, or allowed_agents.

krail --local permissions doctor

Build and inspect the markdown graph:

krail --local graph build
krail --local graph entities --type Package
krail --local graph edges --entity PDDLStream
krail --local graph docs --topic task-and-motion-planning

Build a local vector index:

krail --local vector build
krail --local vector search "dual-arm planning benchmark"
krail --local search "dual-arm planning benchmark" --rag --explain

Ask KRAIL to synthesize from project evidence:

krail --local think "What changed in task and motion planning?"

The think command returns an answer envelope that can include citations, supporting evidence, gaps, conflicts, source freshness, affected documents, graph context, vector hits, and suggested next actions.

Local Project Layout

A KRAIL project is just a directory with repo-backed knowledge files. Typical projects contain:

krail.yaml or rail.yaml
.ontology/
topics/
topics/inbox/
sources/
research_plan/
research_plan/state/
artifacts/
.krail/

The important distinction is:

• topics/inbox/ stores raw captures that still need triage
• topics/ stores durable topic pages and reviewed knowledge
• sources/ stores source records and dependency metadata
• research_plan/ stores tasks, work orders, workflows, decisions, and sessions
• artifacts/ stores outputs that can be checked or promoted
• .krail/ stores local runtime state such as pack selection and vector indexes

Raw captures are not treated as trusted knowledge by default. Promote material only after it is useful, supported, and shaped into stable project records.

Knowledge Modes And Packs

KRAIL supports project modes that tune the ontology, workflow defaults, and agent prompts for different kinds of knowledge work.

Inspect the active mode and pack:

krail --local mode active
krail --local mode list
krail --local pack active
krail --local pack validate

Built-in modes include:

• research: papers, methods, datasets, experiments, claims, evidence, and open questions
• company: teams, systems, policies, workflows, owners, metrics, decisions, and stale docs
• personal: projects, areas, resources, ideas, documents, and notes
• software: services, modules, APIs, dependencies, decisions, incidents, and risks
• project: milestones, decisions, artifacts, risks, blockers, and closeout

CLI Overview

The CLI has two operating styles:

• local mode, using files from a project directory
• API mode, connecting to a KRAIL-compatible local API runtime

Most local commands look like this:

krail --local --path /path/to/project <command>

If you are already inside the project directory, this is enough:

krail --local <command>

Common commands:

krail init <directory>
krail --local doctor
krail --local capture "note"
krail --local inbox list
krail --local topic upsert <topic>
krail --local search "query" --explain
krail --local think "question"
krail --local graph build
krail --local graph check
krail --local vector build
krail --local sources validate
krail --local sources check
krail --local integrity status

Agent and workflow commands:

krail --local agent list
krail --local agent run "summarize new captures" --runner codex_cli --dry-run
krail --local task create "Audit sources" --description "Check stale docs"
krail --local task list
krail --local task dispatch <task_id> --dry-run
krail --local workflow list
krail --local workflow run weekly_literature_refresh --dry-run

Prefer dry runs when dispatching agents or workflows. Dry runs write the work order and session command files without launching a second agent process.

Agent And Runner Integration

KRAIL can connect local knowledge projects to agent CLIs and MCP-compatible agent clients. The goal is not to hide the agent behind an opaque service; the goal is to give agents a durable, auditable workspace with evidence, tasks, workflow state, and project-specific instructions.

There are two integration paths:

• CLI runner dispatch for local tools such as Codex CLI, Claude Code, Gemini CLI, Cursor CLI, and GitHub Copilot CLI
• MCP server tools for clients that can call KRAIL capabilities directly

Local CLI runners

KRAIL can discover configured local runners:

krail --local agent list

It can then create dry-run or executable work orders for a selected runner:

krail --local agent run "summarize new captures" \
  --runner codex_cli \
  --dry-run

The same runner model works through tasks and workflows:

krail --local task create "Audit stale sources" \
  --description "Check source freshness and list affected topic pages." \
  --runner claude_code

krail --local task dispatch <task_id> --dry-run

krail --local workflow run weekly_literature_refresh \
  --runner codex_cli \
  --dry-run

Dry runs are the recommended first step. They materialize the prompt, work order, session command, and project context without launching another process. Full dispatch can then run the selected local CLI once the work order looks right.

This makes KRAIL useful as a coordination layer for agents:

• the repository remains the source of truth
• task instructions are captured as files
• agent outputs can be reviewed before promotion
• workflow runs can be repeated or audited
• project-specific packs and modes shape the work
• doctor, sources, graph, vector, and integrity checks can gate progress

MCP-compatible clients

For tools that support the Model Context Protocol, run the KRAIL MCP server against a local project:

RAIL_LOCAL=1 RAIL_PATH=/path/to/project rail-mcp

MCP clients can then call KRAIL tools for search, think, capture, inbox triage, topic updates, task creation, workflow dispatch, mode inspection, pack inspection, project health checks, graph queries, and integrity status.

In practice, this means an agent can ask KRAIL for evidence before answering, capture useful notes into the project inbox, create a repo-backed task, or run a workflow without inventing its own memory system.

Python API

KRAIL can be used directly from Python.

Local project mode

import rail

project = rail.local("./robotics-kb")

health = project.doctor()
print(health["status"])

results = project.search("graph of convex sets", explain=True)
for hit in results["results"]:
    print(hit["path"], hit.get("score"))

answer = project.think("What evidence do we have about GCS feasibility?")
print(answer["answer"])

API mode

import rail

project = rail.connect(
    "nj-economics",
    api_url="http://localhost:8000/api/v1",
)

df = project.query(
    "SELECT county_name, unemployment_rate "
    "FROM County "
    "ORDER BY unemployment_rate DESC "
    "LIMIT 10"
)

print(df)

Streaming agent responses

import rail

project = rail.connect("nj-economics")

for event in project.agent.ask(
    "Compare Hudson and Bergen County unemployment trends",
    stream=True,
):
    if event["type"] == "text_delta":
        print(event["text"], end="", flush=True)

Search Versus Think

Use search when you need raw document evidence.

krail --local search "customer onboarding workflow" --explain

Use find when you need typed operational and knowledge records in one result envelope, including documents, entities, claims, candidate evidence, artifacts, workflow runs, and queue items.

krail --local find "customer onboarding workflow" --type claim --type workflow_run

Use think when you need a cited answer shape with explicit gaps, conflicts, and next actions.

krail --local think "what changed in onboarding this week?"

Do not promote generated statements into trusted project state until they are registered as claims with evidence and pass the project integrity checks.

Permissions

KRAIL permissions are local-first and backward-compatible. Missing permission metadata means public/project-readable. Add restrictions only where needed:

visibility: private
owner: akash
sensitivity:
  - confidential
allowed_roles:
  - reviewer
allowed_agents:
  - codex_cli

search, find, think, MCP retrieval, and workflow execution use the same policy checks. Denied reads and allowed sensitive reads are appended to research_plan/audit/access.jsonl.

Workflow DAGs

Workflows can remain sequential, or they can opt into dependency-aware execution with needs:

id: repo_intake
dag:
  max_concurrency: 4
steps:
  - id: inspect_manifests
    kind: command
    run: python scripts/inspect.py

  - id: map_dependencies
    kind: command
    run: python scripts/deps.py

  - id: review
    kind: think
    needs: [inspect_manifests, map_dependencies]
    mode: hybrid
    query: summarize repo architecture evidence

Command steps support both retry: 2 and richer retry policies:

retry:
  max_attempts: 3
  backoff_seconds: 10
timeout_seconds: 300

MCP Server

KRAIL projects can be exposed to MCP-compatible clients with the companion MCP server package.

Install from the monorepo during development:

pip install -e packages/mcp-server

Run against a local project:

RAIL_LOCAL=1 RAIL_PATH=/path/to/project rail-mcp

Useful MCP tool families include:

• find: retrieve typed records across docs, graph, integrity, sessions, queues, and artifacts
• search: retrieve document evidence
• think: synthesize evidence with gaps and conflicts
• capture: add local notes or source pointers
• mode_active and mode_list: inspect operating mode
• inbox_list and inbox_promote: triage captures
• topic_list and topic_upsert: manage durable topic pages
• doctor: inspect local project health
• pack_active: inspect the active knowledge pack
• create_task, list_tasks, and dispatch_task: manage worker tasks
• list_workflows and run_workflow: create workflow tasks from the active pack

Source Freshness And Integrity

KRAIL includes local checks for source dependency freshness and research integrity records.

krail --local sources validate
krail --local sources check
krail --local sources affected
krail --local integrity status
krail --local integrity sources
krail --local integrity claims

These commands help separate raw notes from trusted project state. The intended workflow is to capture freely, promote carefully, and keep claims tied to evidence.

Current Status

KRAIL is suitable for pilot projects, local knowledge bases, agent workflow experiments, and research/company/project memory prototypes.

Ready now:

• local project scaffolding
• capture inbox and topic promotion
• deterministic local search
• markdown-frontmatter graph build/query/export
• local SQLite vector database
• deterministic think evidence envelopes
• project health checks
• source dependency checks
• repo-backed tasks, work orders, workflows, and session state
• local CLI runner discovery and dry-run dispatch
• Python client for local and API-backed projects

Still maturing:

• model-backed synthesis and reranking
• external pack installation
• production-grade sandbox enforcement
• remote permission scopes
• hosted UI and managed deployments

Development

From the repository root:

pip install -e packages/rail-py -e packages/mcp-server
PYTHONPATH=packages/rail-py:packages/mcp-server pytest -q packages/rail-py/tests

Build the PyPI package:

python -m pip install --upgrade build twine
python -m build packages/rail-py
python -m twine check packages/rail-py/dist/*

Links

• Repository: https://github.com/AkeBoss-tech/knowledge
• DeepWiki: https://deepwiki.com/AkeBoss-tech/knowledge
• Issues: https://github.com/AkeBoss-tech/knowledge/issues
• PyPI: https://pypi.org/project/krail/

License

MIT