Metadata-Version: 2.5
Name: cairntir
Version: 1.12.3
Summary: Host-neutral memory-first reasoning layer for AI coding agents.
Project-URL: Homepage, https://github.com/pnmcguire480/cairntir
Project-URL: Documentation, https://pnmcguire480.github.io/cairntir/
Project-URL: Repository, https://github.com/pnmcguire480/cairntir
Project-URL: Issues, https://github.com/pnmcguire480/cairntir/issues
Project-URL: Changelog, https://github.com/pnmcguire480/cairntir/blob/main/CHANGELOG.md
Author-email: Patrick McGuire <pnmcguire480@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2026 Patrick McGuire
        
        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.
License-File: LICENSE
Keywords: agent,ai,claude,claude-code,codex,cursor,governance,mcp,memory,reasoning,sqlite-vec
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastembed>=0.4.0
Requires-Dist: mcp<2,>=1.28.1
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pre-commit>=3.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-include-markdown-plugin>=6.0.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.7.7; extra == 'docs'
Provides-Extra: legacy-embeddings
Requires-Dist: sentence-transformers>=3.0.0; extra == 'legacy-embeddings'
Description-Content-Type: text/markdown

# Cairntir

Persistent, local-first memory for AI coding agents. Claude Code, Codex,
Cursor, Qwen Code, and other MCP clients share one searchable project history.

[![PyPI](https://img.shields.io/pypi/v/cairntir.svg)](https://pypi.org/project/cairntir/)
[![CI](https://github.com/pnmcguire480/cairntir/actions/workflows/ci.yml/badge.svg)](https://github.com/pnmcguire480/cairntir/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Cairntir stores decisions, facts, unfinished work, and outcomes as verbatim
*drawers* in a SQLite database you own. A budgeted handoff restores complete
drawers across sessions; semantic and file-anchored recall find deeper evidence.

Current release: **1.11.0**. See the
[release evidence](docs/release/v1.11.0.md) and [changelog](CHANGELOG.md).
Published downloads are on
[PyPI](https://pypi.org/project/cairntir/) and
[GitHub Releases](https://github.com/pnmcguire480/cairntir/releases).

## Install

```bash
pip install --upgrade cairntir
cairntir setup
```

Python 3.11+ is required. Setup initializes the store and configures supported
hosts it detects. Restart your agent afterward.

```bash
cairntir version
cairntir doctor
```

For one host or project, use `cairntir init --host codex`; add `--user` for
user-scope configuration. Cursor's global User Rule requires a manual paste;
setup prints the rule and reports that step.

Follow the [getting-started guide](docs/how-to-use.md) for configuration,
verification, recovery, and troubleshooting.

## Use

Ask your agent to remember a decision in your project's wing, then start the
next task with `cairntir_handoff(wing="myproject")`. A wing is a project, a
room is a topic, and a drawer is one verbatim memory.

```bash
cairntir handoff myproject
cairntir handoff myproject --task "repair cache invalidation" --budget 8192
cairntir recall "why did we choose Postgres?" --wing myproject
cairntir recall-for-change src/auth.py
cairntir recover --host codex --wing myproject
cairntir cost myproject
```

Handoff returns whole drawers or names those omitted by its character budget.
It includes recent default-layer writes, open predictions, and optional code
anchors. Settlements append observed outcomes without rewriting predictions.

[Portable evidence](docs/portable-evidence.md) preserves source identities and
relationships across stores. [Evaluated procedures](docs/evaluated-procedures.md)
require holdout evidence and local approval; [scoped sharing](docs/scoped-sharing.md)
limits access with owner-issued grants.

## Host support

| Surface | Support |
|---|---|
| Setup | Claude Code, Cline, Codex CLI, Copilot CLI, Cursor, Gemini CLI, OpenCode, Qwen Code |
| Transcript recovery | Claude Code, Codex, Qwen Code |
| Other MCP clients | Configure the `cairntir-mcp` stdio command manually |
| Cursor transcripts | Unsupported; an explicit receipt explains the limitation |

Transcript recovery is opt-in, separately budgeted, read-only, and untrusted.
It reads bounded host-owned transcript tails; it cannot recover text the host
never persisted. Saving a recovered request requires explicit selection with
`cairntir recover ... --write N`. Memory is not automatically made
authoritative merely because it appeared in a transcript or imported file.

## Data and safety

The authoritative store is local SQLite with `sqlite-vec`. Embeddings run
locally; first use may download the embedding model. Optional update checks
contact PyPI, and explicitly selected LLM adapters can contact their provider.
Cairntir is not a sandbox for the agent using it.

Portable JSONL verifies content hashes and optionally HMAC signatures through
the Python API. The CLI imports as untrusted and does not verify signatures.
Version 1 cannot safely import source-local history references; use a database
backup for linked history. Export/import also enforce the format's external-URL
restriction. See [data handling](docs/concept.md) for backup and trust boundaries.

## Build and integrate

The MCP server exposes **21 tools** over stdio. Stable Python protocols support
custom backends; see the [integration guide](docs/integration-guide.md).

```text
src/cairntir/
├── memory/       # SQLite storage, embeddings, retrieval
├── mcp/          # stdio server and backend
├── reason/       # prediction, experiment, observation
├── recipes/      # composable workflows
└── cli.py        # cairntir setup | init | handoff | recover | recall | replay | hotfix | doctor | export | import
tests/            # unit, integration, contract, property, evaluation
docs/             # guides, architecture, recipes, release evidence
```

[Contributing](CONTRIBUTING.md) documents the locked development environment
and required checks. Tests enforce at least 80% coverage of the measured
surface; transport entrypoints are excluded and tested separately. The
LongMemEval subset is a regression gate, not a general benchmark claim.

## Documentation

- [Getting started](docs/how-to-use.md)
- [Concepts and data handling](docs/concept.md)
- [Multi-host architecture](docs/architecture/multi-host-continuity.md)
- [Recipes](docs/index.md#recipes): CodeGlass, Decision Replay, Signal Reader,
  Bounded Hotfix, and Finalization Mode
- [Roadmap](docs/roadmap.md)
- [Security policy](SECURITY.md) · [release policy](docs/release-cadence.md)
- [Design principles](ETHOS.md) · [lineage](docs/lineage/brainstormer.md)

Cairntir (*CAIRN-teer*) combines a cairn, a waypoint of stacked stones, with a
seeing-stone. Maintained by Patrick McGuire. [MIT licensed](LICENSE).
