Personal Context

A local-first Codex plugin prototype for maintaining durable knowledge in Open Knowledge Format (OKF). 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. The source is licensed under Apache-2.0. Initial source publication is a baseline for development, not a tagged release. Detailed implementation and migration history remain in the plan and specification.

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 — scoped routing, generic repository OKF, canonical vault/export/refresh and reviewed synchronization.

• Offline OKF format knowledge — verified specification/license packaging, offline examples, profile boundaries and reviewed upstream upgrades.

• Optional source evidence — retain useful supporting material and genuine links without blanket citations.

• Metadata naming and JSON format — dot-prefixed support metadata, readable JSON and the current export format.

• Canonical section context — current schema, reviewed note/batch maintenance, export review and migration from duplicated operational records.

• Context maintained by the working agent — current direction: commit-linked intent, explicit project creation and scoped context transfer into repositories.

• Tasks and preference learning — 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 — readable OKF, selective encryption, retained checkpoints and repository recovery.

• Historical conversation names and context links — opt-in import compatibility, stable identities and source-backed Markdown relationships; current stores use distilled outcomes.

• Reviewed names and preservation — readable canonical paths, explicit source bindings and preservation of reviewed notes.

• Historical conversation consolidation — opt-in compatibility output with retained adapter evidence, conservative duplicate reconciliation and reported ordering uncertainty.

• Historical conversation-owned supporting material — opt-in nested reviews/subagents and pasted-file import compatibility, outside the current context store.

• 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 — onboard knowledge routing, retrieve scoped memories and curate them with the working agent, before Gmail.

• Cross-machine continuity — planned open-project/task inventory and voice-driven creation of fresh tasks with resumption briefs on another machine.

• Plan and milestones — scope, architecture, delivery order and decisions.

• Product specification — requirement IDs and acceptance criteria.

• Context format — OKF version and personal-context conventions.

• Email and OAuth design — Gmail first, extensible providers later.

• Conversation capture and GitOps — historical capture research and the separate bounded specification-to-build design.

• Privacy and storage — what belongs in each repository.

• Project memory setup and operation — encrypted capture, recovery, status and proposal review.

• Backup and recovery — encrypted Git snapshots, separate key recovery and restore drills.

Related MCP server: Cognition Workbench

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:

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:

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

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. Code and documentation are licensed under Apache-2.0. 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.