The MyContextLibrary Spec

A spec and operating guide for building, owning, and using a context library of anything (you, your work, your products, your school, your projects, your life, etc.) with large language models (LLMs).

Preamble

My Context Library is your structured memory of anything you care about - captured in plain files you fully control, organized the way you think, and shareable with AI only when, how, and where you choose. It favors flexibility over rigidity, privacy over convenience, and human-readable text over opaque databases.

This constitution lays out the minimum rules of the road so different people (and tools) can interoperate - without forcing a one-size-fits-all schema.

Purpose

1. Preserve and evolve a durable, searchable record of anything you care about - yourself, your history, your family, your work, your products, your school, your projects, your life, and more.
2. Enable safe, selective sharing of that record with AI to get better, more contextual help.
3. Stay tool-agnostic: Markdown, local folders, version control, any editor, any model.
4. Remain future-proof through open formats and minimal required metadata.

Core Principles

1. You Own It – Files live where you decide (offline, encrypted drives, private repos).
2. Flexibility by Default – Only a bare-minimum header is required; everything else is optional.
3. Privacy First – Sensitivity levels and scopes control what ever leaves your library.
4. Composable Context – Small docs/chunks let you mix and match for any AI conversation.
5. Evolvable Structure – Any single file can grow into a folder with its own sections as you add more information.
6. Transparent History – Version control (git) tracks what changed, when, and why.
7. Interoperability, Not Uniformity – Conventions enable tooling, but individuals can diverge.

Structure & Getting Started

1. Create a simple folder structure on your disk

   MyContextLibrary/  
     agents/        # Agent configurations and definitions
     library/       # The core knowledge base (Me, Work, Projects)
     playbooks/     # Standardized templates and guides
     routines/      # Operational workflows and recurring tasks
     settings/      # System configurations (headers, schemas)
     tools/         # Executable scripts for managing and analyzing data

   This structure provides a robust framework, but it's important to remember it's an example. You don't need to create all these folders if they don't align with your specific needs. The key is to adapt the structure to best serve your context, while adhering to the core principles of organization and semantic clarity.

2. Add your first doc in the library/me folder: fast_facts.md with the MVH header (see below).

   MyContextLibrary/  
     agents/        # Agent configurations and definitions
     library/       # The core knowledge base
       me/
         fast_facts.md
     playbooks/     # Standardized templates and guides
     routines/      # Operational workflows and recurring tasks
     settings/      # System configurations
     tools/         # Executable scripts

3. Congratulations. You just started your first Context Library!

You can always also download a sample MCL library from the official repository with helpful playbooks and settings.

Promotion Rules

Keep individual docs under a single page (~800 tokens). Split when bigger. If you wonder if it's too big, it probably already is.

Example evolution:

• Start with a single file (e.g., me.md).
• When it grows too large or complex: promote it into a folder:
  • Move content into supporting docs (e.g., me/childhood.md) and create an index me/_index.md to identify each document.
• Every folder that has more than one child should contain an _index.md listing its contents and providing quick navigation. Tools can help you generate the index files.

me.md

# when promoted it becomes:
me/
  _index.md
  fast_facts.md
  childhood.md
  childhood/
    _index.md
    schools.md
    friends.md

The Bare Minimum Header (MVH)

Every file meant for the library includes a short YAML front‑matter block. Required keys:

---
title: "My info"                    # The title of the document
abstract: "Includes..."             # Short abstract of the contents of the document (useful for AI and search)
created: "2025-07-23"               # Document creation ISO date
updated: "2025-07-25"               # Last updated ISO date
sensitivity: "private"              # public | private | secret
---

Everything else (tags, next_review, share_policy, etc.) is optional. Add freely.

Scopes, Sensitivity & Sharing Modes

You control how, and if content is shared with models.

Sensitivity Levels (minimum set)

• public - a public document - can be shared with anyone. Can be used by external AI models.
• private - a document that should only be visible to the author. Can be used by external AI models when via interfaces that don't allow training of new models on the data. This should be the default setting for any new documents.
• secret - confidential document. Should not be used with external AI models. Can be used with local (or private) AI model instances. Any documents work related or under NDA should be kept in this category. This is declarative so please keep it in mind when working with AI assistants/agents that have access to all files.

(You can invent additional levels or policies; tools should ignore what they don’t understand.)

Ideal Sharing Patterns (to be used by tools/agents/assistants)

• Manual: You can copy/paste a specific doc into a prompt.
• Semi-automated: A script asks “Include goals + project X?” and assembles context accordingly.
• Local-only: For secret scope, you run a local model; nothing crosses the network.
• Redacted/Masked: Tools apply simple transforms (remove names, fuzz ages) before sending.

Yes, I realise these may be difficult to follow if you just use Claude Code, Gemini CLI or Codex...

Version Control, History & Provenance

• If you can operate it, store the library in a git repo or fork it from the official MCL repo.
• Commit small, meaningful changes with descriptive messages.
• Use branches for big reorganizations; merge when stable.
• Provenance matters: you can trace the evolution of your story and decisions over time.

Optional extras:

• Git hooks to auto-update updated header setting

Optional Conventions (Adopt If Useful)

• Tags & Domains: Add tags: ["work","health"] or a domain: "work" for quick filtering.
• Review Cadence: Add next_review to prompt periodic check-ins.
• Share Policy: Add share_policy: "mask-names" or "forbid" if tools support it.
• Links: Maintain links: arrays between related docs for graph navigation.

None of these are mandatory; they’re there when you feel the pain they solve.

AI Integration Patterns

1. Context Packets: For any task, assemble the smallest set of docs/chunks needed.
2. Agents: Add and keep your personal AI agents/assistants in the agents folder.
3. Local vs. Cloud Models: Route based on sensitivity. For secret, default to local AI models.
4. Audit Trail: Save the prompt + docs used in a session for later review.

MCP & Resource-Friendly Design (Optional)

• Treat each document as a discoverable resource.
• Expose title, abstract, updated_at, sensitivity so clients can list and request only what they need.
• Use simple URIs like mcl://library/me/childhood to fetch content.
• Parameterized “resource templates” can return slices (e.g., decisions from 2024).

This layer is additive - also a future consideration.

Governance & Evolution

• This constitution is a living document.
• When multiple people hit the same problem, we will propose new conventions.
• We will keep the minimum header stable so tools don’t break.

License & Attribution

Licensed under MIT License. Open to anyone.
Use, remix, and share these ideas freely.
Attribute and link to this spec.
The goal is to help people build safer, more useful personal or organizational knowledge systems.