cairnkit

A small agent runtime for business applications. Give an agent useful tools while keeping identity, permissions and persistence in your application. Use proposal tools and a host-controlled review step when a person should decide what gets saved.

A cairn is a pile of stones that marks a trail so the next walker can follow it. cairnkit does the same for agents: approved memory, searchable history and curated skills that the next conversation builds on.

中文说明

See the approval boundary

A fictional support ticket asks to change an invoice email. The agent reads it and creates a draft. The saved record changes only after the host's reviewer approves it. Rejecting the draft leaves the record untouched.

Watch the 35-second walkthrough · Run the example and choose approve or reject

git clone https://github.com/wasabihu/cairnkit.git
cd cairnkit
uv run python examples/approval.py

Offline, fictional data, no API key. The model uses predetermined ScriptedModel responses. The video replays snapshots from a real execution of that example, including a scripted approval choice. It demonstrates the host integration, not model quality. The in-memory review function is example application code, not a built-in approval service.

Why another agent runtime

In a business application, several people may share records, each with different roles. The application needs to retain control over which tools an agent can use and when a proposed change becomes a saved record. cairnkit provides building blocks for that:

• Identity comes from the host, never from the model. Tools receive the signed-in person, their roles and the record being worked on in a ToolContext.
• Make changes reviewable. Tools declare an access level (read, propose, write) and allowed roles. Your proposal handler creates drafts; your application implements approval and persistence. The access label alone does not enforce human review.
• Memory with guard rails. Add / patch / remove edits located by quoted text, size limits, prompt-injection scanning and frozen snapshots, ported from Hermes Agent.
• Compact long conversations. A port of Hermes Agent's context compression: incremental structured summaries, real token anchors, cooldowns and verbatim user quotes.
• Small. The core depends only on the standard library and httpx. No web framework, no database, no vector store: storage and permissions stay in your application.

What is inside

Install

pip install cairnkit
# or
uv add cairnkit
# with document reading (adds pypdf and openpyxl):
pip install "cairnkit[documents]"   # or: uv add "cairnkit[documents]"

Python 3.12 or newer.

Quick start

An agent is a folder:

agents/
  greeter/
    agent.toml
    SOUL.md

# agents/greeter/agent.toml
description = "Answers questions about opening hours."
model = "default"          # a name your application maps to a model
tools = ["opening_hours"]  # the only tools this agent may use
skills = []                # optional: skills from a skills/ folder
max_iterations = 4
temperature = 0.2

SOUL.md holds the persona and rules; it goes into the stable layer of the system prompt.

from cairnkit import Agent, ToolContext, ToolRegistry, load_agents, openrouter, tool_result

tools = ToolRegistry()

@tools.tool(name="opening_hours", description="Opening hours for a weekday.",
            parameters={"type": "object", "properties": {"day": {"type": "string"}},
                        "required": ["day"]})
def opening_hours(args, ctx):
    return tool_result(day=args["day"], hours="7am-7pm")

specs = load_agents("agents")
agent = Agent(specs["greeter"], model=openrouter("openai/gpt-4.1-mini", api_key="..."),
              tools=tools)
result = await agent.run("When do you open on Sunday?", ToolContext(principal={"id": "u1"}))
print(result.text)

Runnable examples, no API key needed:

Rules worth keeping

• Identity is not the model's to decide. Put the user and the record in ToolContext.
• Assemble the system prompt once per conversation. Pass RunResult.system_prompt back as run(system_prompt=...) on later turns so the provider's prompt cache keeps working.
• Prefer access="propose" for anything that changes data, and let a person approve.
• Test offline with ScriptedModel; automated tests should never call a real model.
• Text from users, files and tools is data. Keep it out of the system prompt.

Reading documents (optional)

from cairnkit.documents import DocumentError, Limits, extract_text

try:
    doc = extract_text(data, "price-list.xlsx", limits=Limits(max_chars=40_000))
except DocumentError as exc:
    exc.code  # too_large, empty, unsupported, old_format, image, encrypted, no_text, unreadable, needs_extra
else:
    doc.text, doc.kind, doc.parts, doc.truncated, doc.warnings

• Output is Markdown. Word keeps headings, lists and tables; Excel becomes one table per visible sheet (dates as 2026-11-07); PDF text is marked [Page N].
• The format is judged by content, not only the file name. Old .doc/.xls, pictures and scanned PDFs get their own error codes so your UI can explain what to do.
• Limits on file size, PDF pages, Excel rows and unzipped size. Only text is read; macros and formulas never run.
• Replaceable: register_extractor("pdf", fn) swaps in another reader (MarkItDown, Docling, an OCR service) without changing callers.

Relationship to Hermes Agent

Many mechanisms and algorithms are ported from Hermes Agent v0.23.0 (MIT, Nous Research): the prompt layers, the tool loop, memory editing rules, history search, skills, context compression, background review, curation and delegation. Every ported file names its Hermes source in its header. Hermes is a personal assistant with files, terminals and dozens of platforms; cairnkit keeps the algorithms and replaces storage, configuration and permissions so they fit a multi-user web application. See docs/hermes-porting.md for the map and docs/upgrading-hermes.md for following new Hermes releases. cairnkit is not affiliated with or endorsed by Nous Research.

Versioning

MAJOR.MINOR.PATCH. Before 1.0:

• Patch (0.3.0 → 0.3.1): fixes, tests and docs; upgrade freely.
• Minor (0.3 → 0.4): new features, Hermes updates, or anything that needs changes in your code. CHANGELOG.md says what to change.

Development

uv sync --all-extras
uv run pytest -q && uv run ruff check . && uv run ruff format --check .

See CONTRIBUTING.md. Security reports: SECURITY.md.

License

MIT, see LICENSE. Ported Hermes Agent code keeps its MIT notice in NOTICE.md.