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 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

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

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.
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:

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:

./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

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

Build and route deterministic windows:

./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:

./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

uv run personal-context-gateway

Development inspection:

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.

Tests

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 and THIRD_PARTY_NOTICES.md.

License

Released under the MIT License.