# Cairn Remembers

> A local memory layer for people and compatible AI tools, alongside each AI's native memory and context.
> Release 0.3.3. A SQLite vault on the user's machine, shared by connected AI tools.

## Start here

- [Release and install](https://pypi.org/project/cairn-remembers/0.3.3/)
- [Connect your AI](https://github.com/CairnRemembers/cairn/tree/v0.3.3#wire-up-your-ai)
- [Optional embeddings and dashboard](https://github.com/CairnRemembers/cairn/tree/v0.3.3#advanced-install)
- [License](https://github.com/CairnRemembers/cairn/blob/v0.3.3/LICENSE)

## Facts and boundaries

- Each AI keeps its own native memory. Cairn adds a shared record for connected
  tools; it does not replace or synchronize the models' internal memories.
- Python 3.11+. Base installation: python -m pip install cairn-remembers==0.3.3.
  The base requires NumPy; semantic embeddings and the dashboard are optional extras.
- Vault default: ~/.cairn/cairn.db. SQLite storage, not a plain-text file.
- Cairn does not upload the vault to a Cairn cloud service. Retrieved memory placed
  into a cloud AI chat is sent to that AI provider as context.
- Optional local embeddings require dependencies and a model download on first use.
  Read the platform instructions before installing extras, especially on Linux/WSL.
- Notes preserve an append-only memory record; corrections and voiding retain history.
- MCP tools, the CLI, and supported session hooks provide access. Tool registration
  and optional ambient capture are separate. Installing does not enable capture.
- Verify tools from a fresh AI session; use the full Python path for MCP wiring.
- A newly written note can be read by ID. For a first fetch smoke test, use an exact
  keyword in that note. Run cairn embed before relying on semantic retrieval.
- Run cairn sleep yourself or schedule it with your operating system. It does not
  schedule itself. It maintains embeddings, consolidation, and the graph locally.
- Shared memory does not automatically dispatch another assistant. The user directs
  handoffs between connected clients.
- Source-available under BUSL-1.1, not OSI open source. Free for personal/non-commercial
  use; commercial/business use requires a license. Contact licensing@cairnremembers.com.

## Purpose

Keep a project moving across sessions and connected AIs. One agent can save a
plan with its reasons and open questions; another can read the note by ID and
save a review. The owner can inspect both and direct the next step. This is a
supervised workflow, not automatic agent dispatch.

The optional Garden dashboard provides a human view of projects, topics and
notes. The memory map helps explore connections. Read original records when
assessing a claim; storage and retrieval scores are not truth verification.

## MCP tools in 0.3.3

- cairn_orient: a compact starting view of the vault.
- cairn_note: save a note.
- cairn_fetch: retrieve a compact context pack for a query.
- cairn_search: search stored memories.
- cairn_read: read identified notes in full, within the requested output budget.
- cairn_logs: inspect the recent live tail, including unembedded notes.
- cairn_recent: inspect recent work records.
- cairn_wander: explore related memories.

Install Cairn, connect a compatible app using the setup guide for the installed
version, then fully restart the app. In a new chat, ask its assistant to save a
test note in Cairn and read it back by ID. Use the Python installation that has
Cairn when configuring the connection. Optional capture is configured separately.

## Flexible use

Use one connected assistant or several. Save notes from the CLI, through MCP,
or in Garden. The dashboard and semantic embedder are optional extras.
Supported ChatGPT, Claude and Gemini exports can bring conversation text into
the vault. A separate backfill workflow distills claims. Capture is configured
separately; formats and client integrations determine what detail is available.

The Inside Cairn page contains five recorded interface demos. Private text uses
examples; runtime release parity of the filmed installation is unverified. The
Index clip is a six-second A-section excerpt with example AI and memory topics;
its counts and controls are recorded, and its timing is edited.