Personal API — AI Identity Layer for Your Obsidian Vault

30-second elevator pitch: Stop re-onboarding every AI assistant. This skill scaffolds an "API documentation" for yourself inside your Obsidian vault — ME.md is your identity contract, AGENT.md is your behavior contract. Any AI that reads these two files knows who you are, how you think, and how to work with you in under 30 seconds.

Agent-agnostic by design. This is not tied to any single agent runtime. Drop it next to Claude Code, Codex, Cursor, ChatGPT, Gemini, or your own custom LLM agent — it works the same way: a folder convention + two markdown contracts that any LLM can read.

Why This Exists

Every new chat, every new project, every new AI tool — you start from zero. You re-explain your preferences, your tech stack, your communication style, your constraints. By the time the AI is "calibrated," you've burned 10 minutes and a chunk of context window.

Personal API solves this with three primitives:

1. ME.md — Your single-page identity contract. Read once, AI knows you.
2. AGENT.md — Your behavior contract. Defines the rules of engagement.
3. A vault navigation layer — When AI needs more depth, it knows exactly where to look.

This is built on a real, battle-tested second-brain system (Knowledge Palace v2) used daily by @beiyuii, not a toy demo.

Methodology — Standing on Six Shoulders

Personal API is not just two markdown templates. It is the entry point to a knowledge architecture that fuses six well-established methodologies:

The core formula:

Folders solve lifecycle. MOCs solve topic membership. Wikilinks solve relationships.

Don't make folders carry semantics. The deeper your folder tree, the harder it is to maintain.

Dual-Track Architecture

The vault has two tracks that don't interfere with each other — this is what makes AI collaboration safe:

This separation is the contract. Identity is yours. Knowledge production scales with AI.

Directory Structure

your-vault/
│
├── ME.md                          # ⭐ Layer 0 — Identity entry. AI reads this first.
├── AGENT.md                       # AI behavior contract
├── README.md                      # Vault description (for humans)
├── CLAUDE.md                      # Claude Code instructions (auto-loaded)
├── AGENTS.md                      # Codex / OpenAI Agent instructions
│
├── 00.context/                    # 🟡 Layer 1 — current state (changes fastest)
│   ├── now.md                     # What I'm working on right now
│   ├── open-questions.md          # Unresolved questions
│   └── projects/
│       ├── project-overview.md
│       ├── active/
│       └── archived/
│
├── 10.identity/                   # 🔵 Layer 2 — deep identity (rarely changes)
│   ├── values.md                  # Values & principles
│   ├── vision.md                  # Long-term vision
│   ├── thinking-models.md         # Mental models
│   └── strengths-gaps.md          # Strengths & blind spots
│
├── 20.skills/                     # 🔵 Layer 2 — capability map
│   └── [skill-name].md            # One file per core skill
│
├── 30.knowledge/                  # 🟢 Knowledge production (AI-led)
│   ├── 00.system/                 # 🏛️ Methodology & rules (this skill installs methodology.md here)
│   ├── 10.capture/                # 📥 Inbox — unprocessed material
│   │   ├── inbox/                 # Raw thoughts, links to triage
│   │   └── raw/                   # Source material (papers, articles)
│   ├── 20.intelligence/           # 📡 Time-sensitive industry signals
│   │   ├── ai/
│   │   └── business/
│   ├── 30.research/               # 🔬 Long-form research projects
│   ├── 40.notes/                  # 🗃️ Note core asset
│   │   ├── literature/            # Compiled literature notes (AI-compiled, human-reviewed)
│   │   ├── permanent/             # Atomic Zettelkasten cards
│   │   └── moc/                   # Maps of Content
│   ├── 50.frameworks/             # 🔧 Reusable methods & SOPs
│   │   ├── technical/
│   │   └── operation/
│   ├── 60.projects/               # 📁 Project-bound knowledge
│   ├── 70.outputs/                # 📢 Publishable content
│   └── 90.archive/                # 🗄️ Read-only archives
│
├── 40.memory-stream/              # 📓 Daily logs, reflections, milestones
│   ├── daily/
│   ├── reflections/
│   └── milestones.md
│
└── 50.maps/                       # 🗺️ Global navigation
    ├── index.md                   # Global hub
    └── skills-map.md              # Skills overview

Knowledge flow

Capture → Intelligence/Research → Literature notes → Permanent cards/Frameworks → Projects/Outputs → Archive
   ↕              ↕                       ↕                    ↕                       ↕                ↕
10.capture    20/30                40.literature          40.permanent              60/70           90.archive
                                                          50.frameworks

Installation

One-command setup (recommended)

# 1. Point at your vault
export OBSIDIAN_VAULT_PATH="/path/to/your/vault"

# 2. Run the scaffolder
bash scripts/setup.sh

# 3. Open your vault and fill in the [PLACEHOLDER]s in ME.md and AGENT.md

This creates the full Knowledge Palace v2 directory tree, copies the identity templates, and drops a methodology.md into 30.knowledge/00.system/ so AI agents know the rules immediately.

Manual install

cp templates/ME.md          "$OBSIDIAN_VAULT_PATH/ME.md"
cp templates/AGENT.md       "$OBSIDIAN_VAULT_PATH/AGENT.md"
cp templates/methodology.md "$OBSIDIAN_VAULT_PATH/30.knowledge/00.system/methodology.md"

Usage

After scaffolding, the standard read order for any AI agent is:

1. ME.md — Layer 0, identity (always)
2. 00.context/now.md — Layer 1, current focus
3. 50.maps/index.md — Global navigation
4. 30.knowledge/00.system/methodology.md — Rules of the knowledge production track

Tell your AI assistant:

"Read my ME.md and AGENT.md to understand my context. Then proceed."

Or, with Claude Code, the rules in CLAUDE.md auto-load — no prompt needed.

Prompt examples

AI Operation Boundaries

This is the contract. Pin it.

Frontmatter Spec

Every meaningful note should have:

---
aliases: [Alias 1, Alias 2]    # Obsidian search aliases
updated: YYYY-MM-DD            # Last update — critical for freshness signals
layer: 0/1/2                   # Identity tracks only (0=core, 1=current, 2=deep)
tags: [tag1, tag2]             # Status & type tags
description: One-line summary  # AI-readable file purpose
---

Suggested status & type tags:

Maintenance — Monthly Health Check

Once a month, ask your AI:

"Run a vault health check."

It should scan for:

• Items in 10.capture/inbox/ older than 7 days (stale triage)
• 00.context/ files with outdated project status
• Orphan notes (no backlinks)
• Missing connections (notes that should link but don't)
• Files with updated: older than 3 months on important paths

FAQ

Q: How do I migrate my existing notes in? A: Don't bulk-migrate. Scaffold the structure first, move only what you actively use. Park the rest in 30.knowledge/90.archive/ for traceability.

Q: Do I need frontmatter on every note? A: Important notes — yes (at least updated: and description:). Captures and quick logs — no, until they get promoted.

Q: Can AI write my ME.md for me? A: No. AI can explain each field, but the answers must be yours. This is your digital twin — fake answers fake the twin.

Q: How is this different from plain PARA? A: PARA is action-oriented. Personal API + Knowledge Palace v2 layers Zettelkasten atomic notes, MOC semantic maps, LLM Wiki raw/compiled separation, and the dual-track contract specifically designed for AI collaboration on top of PARA.

Q: What if my AI ignores the rules? A: Use a CLAUDE.md / AGENTS.md at the vault root with hard rules ("Track A is read-only"). Most modern AI tools auto-load these.

Q: Privacy? A: Your filled-in ME.md and AGENT.md contain personal context. Do not commit them to public repos. Add them to .gitignore if your vault is versioned. The skill itself ships only templates, never your data.

Customization

After running setup.sh, edit the templates in your vault. The [PLACEHOLDER] markers show exactly what to fill in. Each field has a comment explaining the intent.

• Update ME.md monthly — identity evolves
• Keep AGENT.md stable — consistency helps AI assistants
• Use [[wikilinks]] to connect related notes
• The layer: frontmatter helps AI prioritize what to read

Tips

• Don't deepen folders. Three levels max. Use MOCs for topical depth.
• Every capture has a half-life. If inbox/ rots for >7 days, you are capturing too much.
• Permanent notes earn their place. A note becomes permanent when it has been linked to twice.
• AI > you at compiling. You > AI at deciding. Let AI drive the literature track. You drive the permanent track.

Related Skills

• personal-knowledge-vault — Cross-project entry skill that lets other AI projects pull context from this vault
• knowledge-palace-builder — Full step-by-step vault construction guide (the original methodology document)

Credits

Designed and battle-tested daily by @beiyuii. Methodology synthesizes work from Tiago Forte, Niklas Luhmann, Nick Milo, Andrej Karpathy, and Johnny Decimal.