An open specification for portable AI context — the files that tell any AI tool who you are, how you work, and what you care about.
Every AI session starts from zero. Your voice, your preferences, your goals, your decisions — rebuilt from scratch in every conversation, every tool, every session. compass-md solves that.
A Compass is a folder of structured markdown files that any AI tool can read. The convention defines the structure, the file purposes, and how agents propose improvements over time. Your context lives in files you own, in a directory you control, readable by anything that implements the spec.
- Pick your storage below — Drive, local folder, or Git
- Follow that setup path (~30–60 minutes)
- Read GETTING_STARTED.md for the daily/weekly rhythm
The rest of this README is the full spec — useful reference, but not required reading to get started.
A specification, not a product. It defines:
- A folder structure any AI agent can read
- Conventions for how agents propose changes to Compass files
- A human review pattern for accepting or rejecting those proposals
- A schema file (
COMPASS.md) that tells agents how to follow the convention
Works with Claude Code, Cursor, Claude.ai, Cowork, ChatGPT, local models — any tool that can read files. No required runtime, no proprietary format, no lock-in.
Every modern AI tool has the same gap: it doesn't know who you are. Each session starts from scratch. Even tools with memory features keep that memory locked in their own product — it doesn't travel.
compass-md proposes a simple, portable Compass any agent can consult and contribute to:
- Your voice, goals, perspectives, and preferences — for personal use
- A team's guidelines, criteria, and accumulated decisions — for shared use
- A project's conventions and standards — for project use
All as markdown files in a known structure. Agents read them before acting. Agents propose refinements when they observe your corrections and decisions. Humans review and accept or reject. The Compass compounds in value over time without requiring active maintenance work.
compass/
├── COMPASS.md ← schema file: tells agents how to follow the convention
├── CLAUDE.md ← tells Claude Code how to use this Compass automatically
├── README.md ← human-readable description of this Compass
├── self/ ← personal context
│ ├── voice.md ← how you write and speak
│ ├── preferences.md ← what you always want and never want
│ ├── facts.md ← stable facts about you
│ ├── decisions.md ← significant decisions and their reasoning
│ ├── sources.md ← signals to monitor; draft triggers for agents
│ └── perspectives/ ← your views on specific topics
│ └── (one file per topic)
├── goals/ ← time-bound targets by domain
│ ├── fitness.md
│ ├── learning.md
│ ├── professional.md
│ └── personal.md
├── team/ ← shared team context
│ ├── guidelines.md
│ ├── style.md
│ ├── feedback_log.md
│ └── criteria/
│ └── (one file per criteria type)
├── refinements/
│ ├── pending/ ← agent-proposed changes awaiting human review
│ ├── accepted/ ← review history of approved changes
│ └── rejected/ ← review history of rejected changes (with reasons)
├── .scripts/ ← git sync agents (Git storage only)
│ ├── compass-push.sh
│ ├── compass-pull.sh
│ └── install-sync.sh
├── log.md ← chronological event log
└── INDEX.md ← optional catalog for large Compasses
Not every Compass needs every folder. A personal Compass might use only self/ and goals/. A team Compass might use only team/. The schema file declares which folders are active.
voice.md — How you write and speak. Tone, vocabulary, sentence structure, things you say, things you avoid. Agents drafting content on your behalf read this first.
# Voice
## Tone
Direct. Lead with the conclusion, then the reasoning.
Short paragraphs — one idea per paragraph.
## Vocabulary
I use: active verbs, specific numbers, dashes for asides
I avoid: "it's worth noting", "perhaps", "circle back", "reach out"preferences.md — Stable preferences. Communication style, decision-making defaults, things you always want and never want from AI tools.
facts.md — Stable facts. Role, location, current context. Things that change rarely.
decisions.md — Significant decisions you've made and why. Append-only. Agents read this to understand precedent and avoid relitigating resolved questions.
sources.md — The signals you want monitored. Any agent performing research, monitoring, or content work reads this first. Contains: sources to watch (forums, blogs, repos, feeds), the signal types you care about, and draft triggers — conditions under which an agent should proactively draft a response rather than just surface a signal.
## Sources
### Forums
- r/LocalLLaMA — daily, high priority
- Hacker News — filter for: inference, local models, agent frameworks
### Blogs and feeds
- simonwillison.net — as published
- Hugging Face blog — weekly
### GitHub repos
- [repo] — watch releases only
- [repo] — watch issues and PRs
## Signal types I care about
[Themes across all sources worth surfacing.]
## Draft triggers
[Conditions under which an agent should draft a reply or post rather than just surface the signal.]perspectives/ — One file per topic you have stated views on. Examples: perspectives/competitive-strategy.md, perspectives/ai-safety.md, perspectives/management.md. Used by agents reasoning about decisions or producing content where your position should be reflected.
Time-bound, status-bearing targets — distinct from perspectives because they change frequently and have current status. One file per domain.
Goals files are the most frequently updated files in a Compass. They give agents a north star when helping you plan, prioritize, or evaluate tradeoffs.
# [Goal domain]
## Target
[What does achieving this look like? Specific and measurable where possible.]
## Current status
[Where are you right now, honestly.]
## Progress markers
[What does meaningful forward motion look like?]
## Constraints and blockers
[What is limiting progress right now?]
## Notes
[Anything an agent should know when helping you work toward this goal.]guidelines.md — Working agreements, standards, and best practices. The constitution for agent behavior on team work.
criteria/ — Evaluation criteria for recurring tasks. Examples: criteria/proposal-review.md, criteria/hiring-screening.md.
style.md — The team's collective voice for external communications.
feedback_log.md — Structured log of feedback observations that should inform future updates to guidelines or criteria.
refinements/pending/ — Where agents place proposed changes to Compass files. Humans review and either accept (applying the change and moving the file to accepted/) or reject (moving to rejected/ with a reason).
refinements/accepted/ — Historical record of accepted refinements.
refinements/rejected/ — Historical record of rejected refinements with reasons. Helps agents learn what kinds of proposals get rejected.
log.md — Append-only chronological log. Each entry: ## [YYYY-MM-DD HH:MM] {event-type} | {description}. Event types: ingest, refinement-proposed, refinement-accepted, refinement-rejected, lint, manual-edit.
INDEX.md — Optional. Catalog of Compass files with one-line summaries. Useful when the Compass grows large enough that an agent benefits from an index before drilling into specific files.
COMPASS.md — The schema file. Tells agents which folders are active, which conventions to follow, and any custom extensions. The most important file in the Compass — spend time on it and iterate.
Before acting on your behalf, an agent reads relevant Compass files:
- Reads
COMPASS.mdto understand the convention - Identifies which files are relevant to the task
- Reads those files (and
INDEX.mdif present) - Acts with that context
Drafting content → self/voice.md + relevant self/perspectives/
Recommendations → self/preferences.md + relevant self/perspectives/
Goal-sensitive tasks → goals/ files
Monitoring or research tasks → self/sources.md
Prior decisions → self/decisions.md
When an agent observes something worth capturing — a corrected output, a new preference, an inconsistency — it writes a proposal to refinements/pending/. Format:
---
proposed_at: 2026-05-22T09:00:00Z
proposed_by: claude-code
target_file: self/voice.md
target_section: "Email tone"
change_type: addition | modification | removal
confidence: low | medium | high
---
## Observation
[What was observed. Specific quotes or examples.]
## Proposed change
[The exact change. Before/after for modifications.]
## Reasoning
[Why this change is warranted.]
## Evidence
[Specific examples supporting the proposal.]
File naming: 2026-05-22-090000_voice-tone-update.md
Agents never modify Compass files directly. All changes go through refinements/pending/.
Agents append to log.md to record significant events. Append-only — never modify past entries.
Direct editing — Humans can edit any Compass file at any time. Note significant changes in log.md.
Reviewing pending refinements — Periodically review refinements/pending/. For each: accept (apply the change, move to accepted/), reject (move to rejected/ with a reason), or edit and accept. compass-dash is the reference review interface — a local dashboard that runs on your machine and handles the accept/reject workflow with auto-apply support.
Lint operations — Ask an agent to scan your Compass for contradictions, stale content, sparse categories, or missing cross-references. Produces a report in lint/{date}.md.
The Compass is just files. Where they live determines which AI tools can access them.
| Google Drive | Local folder | Git repository | |
|---|---|---|---|
| Good for | Multi-device access; Drive-native tools | Privacy; local-first; simplest setup | Audit trail; teams; diff workflows; multi-device sync |
| Works with | Cowork, Claude.ai | Claude Code, Cursor, local models | Claude Code, Cursor |
| Device access | Any device | This machine (or synced) | Any device; auto-synced via included launchd agents |
| Privacy | Google's terms apply | Fully local | Depends on repo visibility |
-
Create a
compassfolder in Drive with the subfolders from the structure above -
Copy templates from
templates/into your Drive structure -
Edit
COMPASS.md— set your name, mark active modules, add engagement notes -
Draft initial content in
self/voice.md,self/preferences.md,self/facts.mdFaster: Use
bootstrap/full-drive-scan.mdto have Cowork scan your Drive and produce drafts automatically. Forgoals/andperspectives/, usebootstrap/interview-perspectives.md— inferred content from documents tends to be wrong for these. -
Connect an AI tool — see
recipes/cowork.md(recommended) orrecipes/claude-ai.md -
Use it for two weeks before optimizing
mkdir -p ~/compass/{self/perspectives,goals,team/criteria,refinements/{pending,accepted,rejected}}
git clone https://github.com/jeffgeiser/compass-md /tmp/compass-md
cp -r /tmp/compass-md/templates/self ~/compass/
cp /tmp/compass-md/templates/COMPASS.md ~/compass/
cp /tmp/compass-md/templates/log.md ~/compass/
cp /tmp/compass-md/templates/CLAUDE.md ~/compass/Edit COMPASS.md, draft initial content, then connect Claude Code:
cd ~/compass && claudeTest: ask it to draft something that requires your voice. The response should cite which Compass files it read. See recipes/claude-code.md for the full setup.
- Create a private repo called
compassand clone it locally - Copy templates as in the local folder setup above
- Edit
COMPASS.mdand draft initial content - Commit your initial Compass
- Install auto-sync across devices (recommended):
bash ~/compass/.scripts/install-sync.shThis installs two launchd agents: one that pushes changes automatically on file save, one that pulls every 5 minutes. Changes on one machine appear on all others within minutes — no manual git push required.
| Tool | What makes it persistent | Where to set it up |
|---|---|---|
| Claude Code | CLAUDE.md in each project |
Paste connect prompt once; AI self-installs |
| Cursor | .cursorrules in each project |
Paste connect prompt once; AI self-installs |
| Claude Cowork | Project custom instructions | Cowork → project → Edit custom instructions |
| Claude.ai Projects | Custom instructions + Compass files added | Claude.ai → project → Custom instructions + Files |
| ChatGPT | Custom GPT with files + system prompt | ChatGPT → Explore GPTs → Create a GPT |
The self-installing connect prompt (from compass-dash Settings) is designed to be pasted once per project. The AI adds a Compass reference block to the project's own config file and every future session in that project is automatically Compass-aware.
See /recipes/ for tool-specific setup instructions.
Templates (/templates/) — Empty markdown files for each Compass category, ready to copy.
Agent integration recipes (/recipes/) — System prompt snippets and instructions for Claude Code, Cursor, Cowork, Claude.ai, ChatGPT, and local Ollama setups.
Bootstrap prompts (/bootstrap/) — Prompts for initializing a Compass from existing material:
full-drive-scan.md— scan Google Drive to produce initial draftslocal-folder-scan.md— scan local documents foldervoice-from-writing-samples.md— focused voice extraction from writing samplesinterview-perspectives.md— conversational interview for perspective filesfacts-from-resume.md— quick bootstrap of facts.md
Helper scripts (/scripts/):
validate-compass.py— checks a folder against the conventionpending-refinements.py— lists pending refinements with summarieslint-compass.py— produces a Compass health report
Examples (/examples/) — Anonymized real Compasses: personal, sales team, research project.
CLAUDE.md / AGENTS.md — Complementary, different purposes. CLAUDE.md describes the project. compass-md describes the person. A developer using both gets project context and personal context in every session.
Karpathy's LLM Wiki — Inspired by this pattern but focused differently. LLM Wiki: topical knowledge base about subjects. compass-md: personal context about the person. Both are valid; they can coexist.
Notion / Obsidian / Roam — The Compass is just markdown. Browse it in Obsidian, sync to Notion — the convention is independent of any specific tool.
Why markdown files and not a database? Markdown is universally readable, human-editable, version-controllable, and consumable by every AI tool. Any structured format introduces dependencies and friction. Markdown is the lowest common denominator that still supports rich content.
Why not MCP? MCP solves agent tool discovery at runtime. The Compass doesn't need that — every modern agent knows how to read files. The convention is the API. An MCP server exposing Compass operations is a valid implementation choice, but not required.
How is this different from ChatGPT custom instructions or Claude memory? Both are tool-specific. Your context lives in their product. You can't take it with you. The Compass is portable and tool-agnostic — the same files work with every tool that can read markdown. You own everything.
What about privacy? The Compass lives in your storage of choice. For maximum privacy, use a local folder — nothing leaves your machine. For team Compasses, apply access controls in your storage system.
How do I bootstrap from nothing?
See /bootstrap/. Drive users start with full-drive-scan.md. Local/Git users start with local-folder-scan.md. Both produce drafts in about an hour that you then review. Perfect bootstrapping isn't necessary — the Compass gets richer through use.
- Use it: Bootstrap your Compass from
/templates/, connect your AI tool via/recipes/ - Integrate it: Add compass-md support to your agent or tool. The refinement format is the integration surface.
- Improve it: File issues for spec gaps. Submit PRs for new recipes, bootstrap prompts, or anonymized example Compasses.
See CONTRIBUTING.md for details.
Current version: v0.1 (initial release) Stability: Pre-stable. Refinements expected based on early adopter feedback. License: MIT
compass-md is an open specification maintained by the community. Created by Jeff Geiser. Implementations and tooling at noorth.ai.
Inspired by:
- Andrej Karpathy's LLM Wiki — the schema-driven LLM-maintained markdown pattern
- Vannevar Bush's Memex (1945) — the original vision of personal curated context
- The CLAUDE.md and AGENTS.md conventions — the meta-file pattern that instructs agents how to operate
- How AI Agent Memory Works by Mert Cobanov — memory architectures: vector stores, knowledge graphs, hierarchical memory
- MemGPT paper — hierarchical memory for stateful agents
- Letta documentation — self-editing memory architectures