# Personal Context

A local-first Codex plugin prototype for maintaining durable knowledge in
[Open Knowledge Format (OKF)](docs/context-format.md). The working agent keeps
repository-specific intent and design alongside its code. A separate private
`personal-context` store holds personal work context, project hubs and repository
links.

**Status: local memory and recovery workflows are implemented.** The plugin
provides scoped memory routing, an offline OKF reference and authoring skill,
canonical Markdown note maintenance, and Project/Repository validation. Its CLI
supports reviewed note changes, selective Git exports, exact refresh with recovery
backups, and restoration into a readable local vault. Ordinary context stays
readable; sensitive files are encrypted on export.

Gmail and other email providers, MCP transport, semantic project/task commands,
pairwise prioritisation, commit-intent enforcement, voice continuation and
specification-driven automation remain planned. Clean-machine onboarding and
fresh-task skill-loading acceptance are outstanding, as are tagged releases and
a supported distribution channel. Routine memory work uses the active agent;
there is no default background conversation ingestion or automatic capture hook.
Historical import helpers remain available for explicit recovery work.

Project repository: [m17kea/personal-context-mcp](https://github.com/m17kea/personal-context-mcp).
The source is licensed under [Apache-2.0](LICENSE). Initial source publication is
a baseline for development, not a tagged release. Detailed implementation and
migration history remain in the [plan](docs/plan.md) and [specification](docs/specification.md).

## Start here

The private `personal-context` repository is an OKF bundle rooted at `index.md`.
Canonical typed Markdown owns work/agent knowledge, repository rows, project
membership and source/name provenance. The current profile has five roots:
`persona`, `agents`, `projects`, `repositories` and `tasks`. Decisions retain their
type within the scope they govern, with one authority linked from other notes.
Conversation outcomes are distilled into their owning notes or repository OKF;
source provenance does not require a transcript bucket. The plugin operates on those section
notes; derived catalog adapters and caches live outside the store. Ordinary
notes stay readable, while export metadata and any sensitive payloads live under
`.metadata/export/`. The plugin is an operational prerequisite; underlying OS
configuration is outside the store. This implementation repository keeps its
normal code layout.

- [Plugin-owned memory operation](docs/memory-takeover.md) — scoped routing, generic repository OKF, canonical vault/export/refresh and reviewed synchronization.
- [Offline OKF format knowledge](docs/context-format.md#plugin-owned-offline-format-knowledge) — verified specification/license packaging, offline examples, profile boundaries and reviewed upstream upgrades.
- [Optional source evidence](docs/canonical-context.md#source-policy-and-presentation) — retain useful supporting material and genuine links without blanket citations.
- [Metadata naming and JSON format](docs/metadata-layout.md) — dot-prefixed support metadata, readable JSON and the current export format.
- [Canonical section context](docs/canonical-context.md) — current schema, reviewed note/batch maintenance, export review and migration from duplicated operational records.
- [Context maintained by the working agent](docs/agent-context.md) — current direction: commit-linked intent, explicit project creation and scoped context transfer into repositories.
- [Tasks and preference learning](docs/tasks-and-priorities.md) — planned standalone tasks, central project to-dos and informative pairwise choices over existing work knowledge; portable evidence and correctable preferences, with Elo as an optional first model.
- [Context export and workspace recovery](docs/migration.md) — readable OKF, selective encryption, retained checkpoints and repository recovery.
- [Historical conversation names and context links](docs/context-format.md#readable-conversation-names-and-linked-context) — opt-in import compatibility, stable identities and source-backed Markdown relationships; current stores use distilled outcomes.
- [Reviewed names and preservation](docs/context-format.md#reviewed-concept-names-and-curated-notes) — readable canonical paths, explicit source bindings and preservation of reviewed notes.
- [Historical conversation consolidation](docs/context-format.md#consolidated-conversation-exports) — opt-in compatibility output with retained adapter evidence, conservative duplicate reconciliation and reported ordering uncertainty.
- [Historical conversation-owned supporting material](docs/context-format.md#conversation-owned-supporting-material) — opt-in nested reviews/subagents and pasted-file import compatibility, outside the current context store.
- [Verified full context refresh](docs/context-format.md#verified-full-context-refresh) — prepare and verify a separate candidate, explicitly migrate readable paths, and apply only proven replacements and cleanup with a private recovery backup. The authorized local refresh and preservation checks passed.
- [Memory-first plugin design](docs/plugin-memory.md) — onboard knowledge routing, retrieve scoped memories and curate them with the working agent, before Gmail.
- [Cross-machine continuity](docs/continuity.md) — planned open-project/task inventory and voice-driven creation of fresh tasks with resumption briefs on another machine.
- [Plan and milestones](docs/plan.md) — scope, architecture, delivery order and decisions.
- [Product specification](docs/specification.md) — requirement IDs and acceptance criteria.
- [Context format](docs/context-format.md) — OKF version and personal-context conventions.
- [Email and OAuth design](docs/email-design.md) — Gmail first, extensible providers later.
- [Conversation capture and GitOps](docs/conversation-and-gitops.md) — historical capture research and the separate bounded specification-to-build design.
- [Privacy and storage](docs/privacy-and-storage.md) — what belongs in each repository.
- [Project memory setup and operation](docs/project-memory.md) — encrypted capture, recovery, status and proposal review.
- [Backup and recovery](docs/backups.md) — encrypted Git snapshots, separate key recovery and restore drills.

## Try the offline prototype

Requires Python 3.11+ on a POSIX system (Linux/macOS). From a fresh checkout,
create an environment and install the declared dependencies before running the
demo, tests or plugin builder:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
PYTHONPATH=src python -m personal_context_mcp demo --output /tmp/personal-context-demo
PYTHONPATH=src python -m unittest discover -s tests -v
```

Encrypted operations require `age`. To include real encryption integration tests,
set `PERSONAL_CONTEXT_AGE_TEST_BINARY` to an installed `age` executable with
`age-keygen` beside it; those tests otherwise report skips.

Build a standalone plugin into a new output directory:

```bash
python scripts/build_plugin.py --output /tmp/personal-context-plugin
python -I /tmp/personal-context-plugin/scripts/cli.py plugin status
```

Choose an unused output path when rebuilding. The artifact includes the plugin runtime,
its YAML dependency and the pinned offline OKF reference. Building does
not install it into Codex or modify a personal store; see the
[plugin recovery guide](docs/plugin-recovery.md) for the package contract.

The demo renders **synthetic, already-extracted** action candidates into task concepts. It demonstrates provenance and stable filenames; it does not infer to-dos from email text or call a model. Existing files are preserved, including user edits. The initial index is also preserved on rerun; reconciliation and index updates are future work. The output is plaintext demo data, not a secure vault. Do not supply real email to this prototype.

## Repository boundaries

This repository contains public code, specifications, synthetic examples, and CI
configuration. The separate private `personal-context` repository holds distilled
OKF concepts and their source provenance in readable form. Only sensitive files
are encrypted on export to Git. The accepted sensitive categories are explicitly
marked private content plus financial, medical and intimate details. Ambiguous or
unsupported files stay local for review; credentials and private keys never enter
Git, including encrypted exports.

The file-level export gate uses local rules and revision-bound review. It does not
claim perfect semantic detection or start automatic synchronization. Sensitive
readable views, email caches, model logs, complete search indexes and OAuth tokens
belong in separate local storage. Older capture/checkpoint formats still encrypt
all records and remain available for recovery. See the
[readable-by-default decision](docs/decisions/0009-readable-by-default.md).

The default direction is local storage with explicit selection of content sent to a chosen cloud model. Provider, model, and storage interfaces should be replaceable. AWS hosting is an optional later deployment profile.

Local restore keeps context, including sensitive concepts, readable as Markdown
outside Git. Sensitive copies are encrypted when exported to the private
repository; ordinary files stay readable there too. Reviewed selective export
and exact refresh reconcile central edits. The working agent follows the chosen
reviewed auto/manual Git sync policy; no background sync is installed.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Code and documentation are licensed under [Apache-2.0](LICENSE). The license does not grant access to any user's private context or source messages. Use synthetic fixtures for contributions; never include personal stores, messages or credentials.