# Chronicle

Chronicle is a local-first, provenance-preserving personal archive with a
read-only Model Context Protocol (MCP) gateway. It preserves files and supported
AI conversation exports, derives evidence-linked candidate memories with local
models, and retrieves only the context needed for a particular question.

Chronicle is an early-stage research prototype. It is not a backup replacement,
medical system, or authority on a person's identity.

## Why Chronicle exists

Long-term AI memory must retain useful detail without sending an entire digital
life to every model on every request. Chronicle separates the work:

1. Original inputs are archived with hashes, timestamps, and provenance.
2. Apple's on-device model performs fast routing when available.
3. Qwen through LM Studio proposes detailed, evidence-cited memories.
4. Deterministic validators reject unsupported, malformed, or unsafe claims.
5. A read-only MCP gateway provides bounded search-then-fetch retrieval.

Derived claims remain reviewable candidates linked to their original evidence;
model output does not automatically become an authoritative profile.

## Current capabilities

- Content-addressed local archive with SHA-256 integrity checks
- Immutable versions when source files change
- SQLite full-text search and provenance metadata
- Lossless import of supported Claude conversation exports
- Deterministic, turn-preserving conversation windows
- Apple Foundation Models routing on compatible Macs
- Resumable Qwen candidate extraction through LM Studio
- Exact evidence-quote and speaker-authority validation
- Sensitive-topic escalation and identifier blocking
- Progress reporting and repeated-failure quarantine
- Page-aware PDF memory with bounded retrieval
- Read-only MCP overview, search, and exact-fetch tools
- Optional delegated Google and Microsoft read connectors

Chronicle contains no send, delete, shell, or computer-control MCP tools.

## Requirements

Core:

- Python 3.11 or newer
- [`uv`](https://docs.astral.sh/uv/) for installation
- macOS, Linux, or Windows for the archive and MCP gateway

Reference configuration matching the original development machine:

- Apple-silicon Mac with Apple Intelligence enabled
- macOS with the Foundation Models framework available
- Xcode/Swift toolchain capable of building the helper package
- LM Studio local server on `127.0.0.1:1234`
- `qwen/qwen3-14b`, MLX 4-bit, with an 8,192-token context

The Apple helper is optional. It checks `SystemLanguageModel.default` at runtime.
Chronicle does not access Siri's private system-wide index.

## Installation

```bash
git clone https://github.com/The-Sequence/chronicle.git
cd chronicle
uv sync --extra dev
cp .env.example .env
./chronicle system-status
```

The `chronicle` wrapper uses the project virtual environment. You may use
`uv run personal-context-archive` instead.

### Build the optional Apple helper

```bash
cd apple-helper
swift build -c release
cd ..
./chronicle system-status
```

If unavailable, confirm that the device supports Apple Intelligence, it is
enabled, and its model has finished downloading.

## Configure LM Studio

1. Install [LM Studio](https://lmstudio.ai/).
2. Download `qwen/qwen3-14b` in MLX 4-bit format.
3. Load the model with context length `8192`.
4. Open **Developer → Local Server**.
5. Use port `1234`; leave **Serve on Local Network** disabled.
6. Start the server.

Use these `.env` values:

```dotenv
PCG_LM_BASE_URL=http://127.0.0.1:1234/v1
PCG_LM_MODEL=qwen/qwen3-14b
PCG_LM_API_KEY=lm-studio
PCG_TRIAGE_MAX_CHARS=24000
```

The placeholder key is used because the compatible request format expects one.
If LM Studio authentication is enabled, use a real local token and never commit
it.

## Safe first run

Do not begin with a home directory. Test a small disposable folder:

```bash
./chronicle scan "/absolute/path/to/small-test-folder"
./chronicle work-status
./chronicle search "sample topic"
```

Private runtime data defaults to `./personal-archive`. That directory, `.env`,
exports, caches, and model artifacts are excluded from Git.

Before using valuable data:

- use FileVault or another encrypted volume;
- back up `chronicle.sqlite3` and the `objects` directory;
- keep LM Studio bound to localhost;
- explicitly allowlist source folders;
- never configure an entire home directory as a local root.

## Import an AI conversation

```bash
./chronicle import-conversations "/path/to/conversation.json"
./chronicle conversation-status
./chronicle search-conversations "topic or decision"
```

Build and route deterministic windows:

```bash
./chronicle plan-conversation 1 --limit 12
./chronicle build-conversation-windows 1
./chronicle route-conversation 1 --limit 10
./chronicle conversation-route-status 1
```

Run bounded detailed extraction:

```bash
./chronicle preview-extraction 1
./chronicle extract-conversation 1 --max-segments 1
./chronicle extraction-progress 1
./chronicle candidate-status 1
./chronicle candidates 1 --limit 100
```

`partial` means valid candidates were checkpointed while other proposals were
rejected. After three validation failures, a segment is visibly quarantined so
later segments can continue; it is not silently treated as successful.

## Run the read-only MCP gateway

```bash
uv run personal-context-gateway
```

Development inspection:

```bash
uv run mcp dev src/context_gateway/server.py
```

Remote deployment requires HTTPS and per-client OAuth authorization in front of
`/mcp`. Give each client an independent, revocable credential. Never put bearer
secrets in URLs.

## Optional provider access

Start read-only with delegated permissions:

- Gmail: `gmail.readonly`
- Google Calendar: `calendar.events.readonly`
- Outlook mail: `Mail.Read`
- Microsoft Calendar: `Calendars.Read`
- Identity: `openid profile offline_access User.Read`

Teams is deferred because school and workplace tenants often require
administrator approval. Chronicle does not bypass tenant policy.

## Privacy model

The public repository contains no archive, extracted memories, conversations,
OAuth tokens, model files, machine-specific paths, or private Git history.

- Source text is untrusted data, never model instructions.
- Filesystem reads are restricted to explicit roots.
- Symlink escapes, traversal, oversized files, and disallowed extensions fail.
- MCP responses are bounded and provenance-rich.
- Raw sources remain authoritative.
- Derived memories retain evidence and extraction-version metadata.
- Sensitive identifiers are blocked from derived memory.
- Failures remain visible, retryable, or quarantined.

See [SECURITY.md](SECURITY.md).

## Tests

```bash
uv run pytest -q
```

Tests use synthetic fixtures only and require no personal files or accounts.

## Status

Chronicle is under active development. Planned work includes candidate review,
contradiction-aware consolidation, compact low-token retrieval summaries,
authenticated remote MCP deployment, and additional approved importers.

## Attribution

Chronicle is independent and is not affiliated with Apple, Anthropic, LM Studio,
Qwen, Sentient OS, OpenAI, OpenClaw, or the MCP maintainers.

Publicly documented local-first and staged-memory patterns—particularly Sentient
OS—informed the architecture. Chronicle's code, prompts, schemas, and tests were
independently implemented. See [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md) and
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## License

Released under the [MIT License](LICENSE).