cairnkit 0.5.0__tar.gz

cairnkit-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --all-extras --frozen
+      - run: uv run pytest -q
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run python examples/minimal.py
+      - run: uv run python examples/approval.py

cairnkit-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+# Push a tag such as v0.5.0 to publish to PyPI. The version in pyproject.toml must match the tag.
+# PyPI side (once): a trusted publisher for this repo, workflow release.yml, environment "pypi".
+name: Release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --all-extras --frozen
+      - run: uv run pytest -q
+      - name: Tag matches the package version
+        run: |
+          version=$(uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          test "v$version" = "$GITHUB_REF_NAME"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+  github-release:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Release notes from CHANGELOG.md
+        run: awk -v t="## $GITHUB_REF_NAME " '/^## /{if (p) exit; if (index($0, t) == 1) {p=1; next}} p' CHANGELOG.md > notes.md
+      - run: gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1 || gh release create "$GITHUB_REF_NAME" dist/* --title "cairnkit $GITHUB_REF_NAME" --notes-file notes.md
+        env:
+          GH_TOKEN: ${{ github.token }}

cairnkit-0.5.0/.gitignore

@@ -0,0 +1,20 @@
+# Upstream Hermes source: a separate checkout, see reference/README.md
+reference/hermes-agent/
+
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.env
+.env.*
+*.sqlite*
+*.db
+*.log
+.DS_Store
+dist/
+build/
+*.egg-info/
+data/
+logs/
+.run/

cairnkit-0.5.0/AGENTS.md

@@ -0,0 +1,24 @@
+# Guidelines for contributors and AI coding assistants
+
+Read this before changing the repository.
+
+- **Stay independent.** Only general runtime capabilities belong here: no business code,
+  databases or web frameworks. The core depends only on the standard library and `httpx`.
+  Features that need more go in optional modules (for example `documents`, installed with
+  `cairnkit[documents]`); core modules must not import them. Storage, permissions, price
+  tables and wording come from the host through parameters, callbacks or configuration.
+- **Identity and permissions come from the host** through `ToolContext`; the model never
+  decides who is acting. Prefer `access="propose"` for writes.
+- **Keep Hermes' design where it fits.** Ported files name their Hermes version, commit and
+  source file in the header, and [NOTICE.md](NOTICE.md) keeps the MIT notice. Record
+  differences and their reasons in [docs/hermes-porting.md](docs/hermes-porting.md).
+  Follow [docs/upgrading-hermes.md](docs/upgrading-hermes.md) for new Hermes releases.
+- A conversation's system prompt does not change, except through context compression.
+- **Tests never use the network.** Use `ScriptedModel`. Real-model checks need a stated
+  purpose and the maintainer's agreement.
+- Never commit keys, runtime data, logs or virtual environments.
+- Adding or upgrading dependencies needs the maintainer's agreement.
+- **Public API changes need a release**: bump the version as described in the
+  [README](README.md#versioning), update [CHANGELOG.md](CHANGELOG.md), tag the commit.
+- Before committing: `uv run pytest -q && uv run ruff check . && uv run ruff format --check .`
+- Keep other people's uncommitted work; stage files one by one.

cairnkit-0.5.0/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+Versioning rules: see [README](README.md#versioning).
+
+## v0.5.0 (2026-11-09)
+
+Follows Hermes Agent v0.23.0 (`2bd378e`). What was taken, skipped or left for later, and why:
+[docs/hermes-porting.md](https://github.com/wasabihu/cairnkit/blob/v0.5.0/docs/hermes-porting.md#v0230-2bd378e-checked-2026-11-09).
+
+- **On PyPI.** Install with `pip install cairnkit` or `uv add cairnkit`; releases are
+  published from a tag (`.github/workflows/release.yml`).
+- New example `examples/verify_citations.py`: a read tool that checks a draft's DOIs and PMIDs
+  with [claimcite](https://github.com/wasabihu/claimcite) before a person reviews it.
+
+New (optional, existing code keeps working):
+
+- `ContextCompressor(fallback_model=...)`: when a separate summary model fails (dead
+  endpoint, quota, unknown model, bad key), the summary is retried once on this model,
+  usually the agent's main model. `CompressionResult.fallback_model_used` and
+  `summary_model_error` say it happened, so the host can warn that the summary model is broken.
+- `ClassifiedError.context["timeout_phase"]` (`"connect"` or `"read"`), and timeout messages
+  that say whether a connection was made and what to change. `AllModelsFailed` repeats them.
+
+Changed behaviour:
+
+- Compression summaries have a `## Unverified / Working Hypotheses` section and the prompt asks
+  for uncertain claims as `UNVERIFIED: <claim> — <basis>` lines, so guesses no longer turn into
+  facts. Hosts with their own `summary_sections` get the label rule without the section.
+- The lean compression tail never exceeds half the trigger, so a small `threshold_tokens` on a
+  large window can get below the trigger again.
+- A 400 that names a request-body byte cap (Novita, Z.AI, "content-length ... bytes") is
+  `payload_too_large` and triggers compression instead of a format error.
+- Streamed tool calls: a new id at an index already in use starts a new call only when it is
+  named and the previous call's arguments are complete. Ollama's parallel calls (all at index
+  0) are now separate calls; LM Studio, Kimi and MiniMax fragments stay one call.
+- Tool results: a JSON result counts as failed when it has a non-empty `error`, a `status` of
+  `failed`/`error`, or a `results` list where every item has an error (before, only
+  `success: false`). This affects loop protection and `ToolRecord.failed`. A rate-limited
+  failure no longer counts toward the identical-arguments warning and block.
+- Memory tool: the schema lists only `target` and `operations` (a single change is a one-item
+  list). The single-change shape and the `new_text` alias are still accepted. Batches that
+  only remove, or a lone duplicate add, are no longer refused when the store is over a lowered
+  limit, and a lone add over the limit says how many characters to free.
+- `history_search` with no arguments lists 10 documents by default (a search still returns 3).
+- `REVIEW_INSTRUCTION` tells the reviewer to save only facts grounded in the conversation, never
+  inferred traits or one-off requests as standing preferences.
+
+## v0.4.1 (2026-10-22)
+
+- `documents`: text and Markdown files saved as Simplified Chinese by older Windows tools
+  (GBK / GB18030) are now read correctly instead of as Windows-1252 garbage. The result
+  carries a warning saying how the text was read. Western legacy text is unchanged.
+
+## v0.4.0 (2026-10-22)
+
+- `make_delegate_tool(..., on_child_run=...)`: a hook that sees every finished child run
+  (agent, result, parent context), so child model calls can be billed. The parent's
+  `RunResult.usage` still covers only its own calls.
+- `generate_title(..., on_usage=...)`: receives the title call's token usage, also when the
+  title is rejected.
+- `RunResult.compression_usage` and `CompressionResult.usage`: what the summary model used
+  when compaction ran, so it can be billed too.
+
+All are additions (optional arguments or new fields); existing code keeps working unchanged.
+
+## v0.3.0 (2026-10-21)
+
+First public release. The project was developed privately as `agentcore`.
+
+- **Renamed to cairnkit.** The package, the import name and the repository are now
+  `cairnkit`. To upgrade from `agentcore` 0.2: change the dependency to
+  `cairnkit` (or `cairnkit[documents]`), point the source at
+  `https://github.com/wasabihu/cairnkit` tag `v0.3.0`, and replace `agentcore` with
+  `cairnkit` in imports. Nothing else changed in the API.
+- English documentation, contribution and security guides, CI on Python 3.12 and 3.13,
+  `py.typed`, and two more examples (`approval.py`, `read_document.py`).
+
+## v0.2.0 (2026-10-21)
+
+- Optional module `documents`: PDF, Word (.docx), Excel (.xlsx) and text to Markdown
+  (`extract_text`), with limits on size, pages, rows and unzipped size, stable error codes
+  (`DocumentError.code`) and replaceable readers (`register_extractor`).
+- Optional dependency group `documents` (pypdf, openpyxl). Core dependencies unchanged.
+
+## v0.1.0 (2026-10-21)
+
+First version as a standalone package, based on Hermes Agent v0.22.2 (`d923a5e`).
+
+- Agent loop (streaming, tool rounds, loop protection, forced final answer)
+- Tool registry with access levels and roles; three-layer system prompt; skills shown on
+  demand with injection scanning
+- Memory editing rules (add / patch / remove), history search, background review,
+  delegation to sub-agents
+- Context compression following Hermes' full implementation (token anchors, cooldowns,
+  anti-thrashing, incremental summaries, forced compaction and retry on overflow)
+- Skill curation (returns a plan; the host decides)
+- Models: OpenAI-compatible client, OpenRouter, error classification, fallback chain,
+  offline scripted model; cost estimates; automatic titles
+- `scripts/hermes_changes.py` and the Hermes upgrade guide

cairnkit-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for helping. cairnkit is small on purpose, so please open an issue to discuss a new
+feature before writing it. Bug fixes, tests and documentation improvements are welcome
+directly as pull requests.
+
+## Set up
+
+```bash
+git clone https://github.com/wasabihu/cairnkit
+cd cairnkit
+uv sync --all-extras
+uv run pytest -q && uv run ruff check . && uv run ruff format --check .
+```
+
+## What a good change looks like
+
+- It follows [AGENTS.md](AGENTS.md): the core stays dependency-light, identity comes from
+  the host, and tests run offline with `ScriptedModel`.
+- It has tests for the behaviour it adds or fixes.
+- Public API changes are described in [CHANGELOG.md](CHANGELOG.md) under an "Unreleased"
+  heading.
+- Code ported from Hermes Agent names its source in the file header.
+
+## Reporting bugs
+
+Include the cairnkit version, Python version, a minimal script that shows the problem
+(with `ScriptedModel` if possible) and what you expected. For security problems, see
+[SECURITY.md](SECURITY.md) instead of opening a public issue.
+
+By contributing you agree that your contribution is licensed under the MIT License.

cairnkit-0.5.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 wasabihu
+Copyright (c) 2025 Nous Research (portions adapted from Hermes Agent, see NOTICE.md)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cairnkit-0.5.0/NOTICE.md

@@ -0,0 +1,31 @@
+# Notice
+
+cairnkit ports the design and several algorithms of **Hermes Agent v0.23.0**
+(<https://github.com/NousResearch/hermes-agent>, commit `2bd378e`).
+
+```
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Files that contain ported or adapted code say so in their header, naming the
+Hermes source file.

cairnkit-0.5.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.5
+Name: cairnkit
+Version: 0.5.0
+Summary: A small agent runtime for business apps: the host owns identity, writes become drafts a person approves.
+Project-URL: Homepage, https://github.com/wasabihu/cairnkit
+Project-URL: Repository, https://github.com/wasabihu/cairnkit
+Project-URL: Issues, https://github.com/wasabihu/cairnkit/issues
+Project-URL: Changelog, https://github.com/wasabihu/cairnkit/blob/main/CHANGELOG.md
+Author-email: wasabihu <wasabi.net@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE.md
+Keywords: agent-runtime,agents,ai,context-compression,hermes-agent,human-in-the-loop,llm,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: documents
+Requires-Dist: openpyxl<4,>=3.1; extra == 'documents'
+Requires-Dist: pypdf<7,>=6; extra == 'documents'
+Description-Content-Type: text/markdown
+
+# cairnkit
+
+[![CI](https://github.com/wasabihu/cairnkit/actions/workflows/ci.yml/badge.svg)](https://github.com/wasabihu/cairnkit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)
+
+**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.
+
+[中文说明](README.zh-CN.md)
+
+## 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.
+
+![Five steps: source ticket, read, pending draft, human review, host save](docs/assets/approval-demo.gif)
+
+[Watch the 35-second walkthrough](docs/assets/cairnkit-approval-demo.mp4) ·
+[Run the example and choose approve or reject](docs/approval-demo.md)
+
+```bash
+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
+
+| Area                 | Module                       | What it does                                                                                                   |
+| -------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Agent loop           | `loop.py`                    | Model → tools → model, streaming, a forced plain answer when the step budget runs out                          |
+| Tools                | `tools.py`                   | Schema, handler, access level, allowed roles; identity is injected, never taken from the model                 |
+| Loop protection      | `guardrails.py`              | Warns or stops on repeated failing calls and identical results                                                 |
+| System prompt        | `prompt.py`                  | Stable / context / volatile layers, assembled once per conversation for prompt caching                         |
+| Memory               | `memory.py`, `memory_ops.py` | Hermes' add / patch / remove rules; your store decides whether changes need approval                           |
+| History search       | `search.py`                  | One tool, four modes (search, read, context, browse); no model calls                                           |
+| Skills               | `skills.py`                  | `SKILL.md` folders, shown on demand, scanned for injection when loaded                                         |
+| Context compression  | `compression.py`             | Four-phase compaction with incremental summaries and per-conversation `CompressionState`                       |
+| Background review    | `review.py`                  | After a turn, a forked agent decides whether anything should be remembered                                     |
+| Delegation           | `delegate.py`                | Hand a focused task to a specialist agent and get back only its answer (one level deep)                        |
+| Skill curation       | `curator.py`                 | Marks unused skills stale, suggests archives and merges; returns a plan, you decide                            |
+| Injection scanning   | `security.py`                | Prompt injection, hidden characters and exfiltration patterns                                                  |
+| Titles               | `titles.py`                  | Instant title, upgraded by a small model; never overrides a title the user typed                               |
+| Models               | `llm/`                       | OpenAI-compatible client (streaming), OpenRouter, error classification, fallback chain, offline scripted model |
+| Cost                 | `pricing.py`                 | Uses the provider's reported cost, otherwise a price table                                                     |
+| Agent definitions    | `agents.py`                  | One folder per agent: `agent.toml` + `SOUL.md`                                                                 |
+| Documents (optional) | `documents.py`               | PDF, Word, Excel and text to Markdown, with size and zip-bomb limits                                           |
+
+## Install
+
+```bash
+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
+```
+
+```toml
+# 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.
+
+```python
+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:
+
+| Example                                                | Shows                                                      |
+| ------------------------------------------------------ | ---------------------------------------------------------- |
+| [examples/minimal.py](examples/minimal.py)             | The smallest complete agent with one tool                  |
+| [examples/approval.py](examples/approval.py)           | Read a ticket, propose a change, approve or reject in the host |
+| [examples/read_document.py](examples/read_document.py) | Reading a PDF, Word or Excel file into Markdown            |
+| [examples/verify_citations.py](examples/verify_citations.py) | A read tool that checks a draft's DOIs and PMIDs with [claimcite](https://github.com/wasabihu/claimcite) before review (needs network: `uv run --with claimcite python examples/verify_citations.py`) |
+
+## 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)
+
+```python
+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](https://github.com/NousResearch/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](docs/hermes-porting.md) for the map and
+[docs/upgrading-hermes.md](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](CHANGELOG.md) says what to change.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest -q && uv run ruff check . && uv run ruff format --check .
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE). Ported Hermes Agent code keeps its MIT notice in
+[NOTICE.md](NOTICE.md).