OMP Cognitive Filesystem — Complete Manifest

The cognitive filesystem is how OMP (Oh My Pi) discovers, loads, and injects context, rules, skills, agents, hooks, tools, prompts, and memory into every session — automatically. No --read AGENTS.md needed; it’s already in your <context> block.

Source of truth: oh-my-pi/docs/context-files.md · oh-my-pi/docs/skills.md · oh-my-pi/docs/hooks.md · oh-my-pi/docs/system-prompt-customization.md

🧠 Quick-Start Cheat Sheet

# ╔══════════════════════════════════════════════════════════════════╗
# ║  OMP COGNITIVE FILESYSTEM — WHAT IT LOADS & WHERE               ║
# ╠══════════════════════════════════════════════════════════════════╣
# ║                                                                  ║
# ║  CONTEXT FILES (injected as <context> block)                    ║
# ║  ├─ ~/.omp/agent/AGENTS.md        ★ user-level, HIGHEST PRIO   ║
# ║  ├─ <repo>/.omp/AGENTS.md        ★ project, nearest wins       ║
# ║  ├─ <repo>/.claude/CLAUDE.md        user + cwd only              ║
# ║  ├─ ~/.claude/CLAUDE.md            user-level                    ║
# ║  ├─ <cwd>/.gemini/GEMINI.md       user + cwd only              ║
# ║  ├─ <cwd>/.codex/AGENTS.md       user-level only               ║
# ║  ├─ ~/.codex/AGENTS.md            user-level                    ║
# ║  ├─ ~/.config/opencode/AGENTS.md  user-level only               ║
# ║  ├─ ~/.agent/AGENTS.md            user + ancestor walk-up       ║
# ║  ├─ ~/.agents/AGENTS.md           user + ancestor walk-up       ║
# ║  ├─ <cwd>/.github/copilot-instructions.md  cwd + global       ║
# ║  └─ ./AGENTS.md                   project (agents-md)           ║
# ║                                                                  ║
# ║  STICKY RULES (always-apply, re-attached near current turn)     ║
# ║  ├─ ~/.omp/agent/RULES.md         user-level                     ║
# ║  └─ <repo>/.omp/RULES.md         nearest ancestor wins         ║
# ║                                                                  ║
# ║  SYSTEM PROMPT                                                    ║
# ║  ├─ <cwd>/.omp/SYSTEM.md         replaces block 0              ║
# ║  ├─ ~/.omp/agent/SYSTEM.md        user-level                     ║
# ║  ├─ <cwd>/.omp/APPEND_SYSTEM.md  appends to prompt              ║
# ║  ├─ ~/.omp/agent/APPEND_SYSTEM.md user-level                     ║
# ║  └─ ~/.omp/agent/TITLE_SYSTEM.md  session title prompt           ║
# ║                                                                  ║
# ║  SKILLS (optional capability packs via SKILL.md)                 ║
# ║  ├─ <repo>/.omp/skills/*/SKILL.md   project (native)           ║
# ║  ├─ ~/.omp/agent/skills/*/SKILL.md   user (native)              ║
# ║  ├─ <repo>/.agent/skills/*/SKILL.md project (agents)           ║
# ║  ├─ <repo>~/.claude/skills/*/SKILL.md project (claude)         ║
# ║  ├─ <repo>/.github/skills/*/SKILL.md project (github)          ║
# ║  └─ /skill:<name> slash command     interactive invocation      ║
# ║                                                                  ║
# ║  AGENTS (custom subagent definitions)                            ║
# ║  ├─ <repo>/.omp/agents/*.md         project (native)           ║
# ║  ├─ ~/.omp/agent/agents/*.md         user (native)              ║
# ║  ├─ <repo>~/.claude/agents/*.md     project (claude compat)     ║
# ║  └─ ~/.claude/agents/*.md            user (claude compat)       ║
# ║                                                                  ║
# ║  HOOKS (event-driven interceptors, .ts/.js)                      ║
# ║  ├─ <repo>/.omp/hooks/<event>/*.ts   project                   ║
# ║  ├─ ~/.omp/agent/hooks/<event>/*.ts   user                      ║
# ║  ├─ <repo>/.claude/hooks/*.md         project                  ║
# ║  └─ Events: tool_call, tool_result, session_start, etc.        ║
# ║                                                                  ║
# ║  TOOLS (custom tool Extensions)                                  ║
# ║  ├─ <repo>/.omp/tools/               project                   ║
# ║  ├─ ~/.omp/agent/tools/               user                      ║
# ║  ├─ package.json "omp.extensions"      npm packages              ║
# ║  └─ --extension / -e <path>           CLI override             ║
# ║                                                                  ║
# ║  PROMPTS (custom prompt templates)                               ║
# ║  ├─ <repo>/.omp/prompts/             project                   ║
# ║  ├─ ~/.omp/agent/prompts/             user                      ║
# ║  └─ /<name> slash command             interactive invocation    ║
# ║                                                                  ║
# ║  MCP SERVERS                                                     ║
# ║  ├─ ~/.omp/agent/mcp.json             user                      ║
# ║  ├─ <repo>/.omp/.mcp.json           project                    ║
# ║  ├─ <repo>/.claude/settings.json    claude compat             ║
# ║  └─ <repo>/.github/copilot-instructions.md (also rules)      ║
# ║                                                                  ║
# ║  MEMORY (persistent session memory)                              ║
# ║  ├─ ~/.omp/agent/memory/              local backend             ║
# ║  ├─ memory://root                    project memory summary    ║
# ║  └─ Hindsight server (cloud/self-hosted) backend               ║
# ║                                                                  ║
# ║  CONFIG                                                          ║
# ║  ├─ ~/.omp/agent/config.yml          user                       ║
# ║  ├─ <repo>/.omp/config.yml         project                     ║
# ║  └─ --config <yaml>                CLI overlay                ║
# ║                                                                  ║
# ╚══════════════════════════════════════════════════════════════════╝

1. Context Files (Advisory Background)

Behavior: Discovered automatically → injected as <context> block in opening prompt. Read as plain Markdown. Not rules — advisory.

Provider Priority (highest wins at same depth)

Priority	Provider	User Location	Project Location	Walk-up?
100	`native`	`~/.omp/agent/AGENTS.md`	`<repo>/.omp/AGENTS.md`	✅ nearest ancestor
80	`claude`	`~/.claude/CLAUDE.md`	`<cwd>/.claude/CLAUDE.md`	❌ cwd only
70	`agents`	`~/.agent/AGENTS.md`, `~/.agents/AGENTS.md`	`.agent/AGENTS.md`, `.agents/AGENTS.md`	✅ ancestor
70	`codex`	`~/.codex/AGENTS.md`	—	❌ user only
60	`gemini`	`~/.gemini/GEMINI.md`	`<cwd>/.gemini/GEMINI.md`	❌ cwd only
55	`opencode`	`~/.config/opencode/AGENTS.md`	—	❌ user only
30	`github`	`~/.copilot/copilot-instructions.md`	`<cwd>/.github/copilot-instructions.md`	❌ cwd only
10	`agents-md`	—	`./AGENTS.md`	✅ to repo root

Shadowing Rules

One user context — highest priority wins (native ~/.omp/agent/AGENTS.md shadows all others).
One project context per directory depth — nearest config dir wins at that depth.
Across depths, multiple survive — ancestor + package-level both load.
Farther ancestors appear first, closer files appear last (more prominent).

`@` Imports

Tokens expand inline before injection:

Read @docs/architecture.md before changing storage.
Shared steps in @../RELEASE.md, aliases in @~/.notes/aliases.md.

Rules:

Relative paths resolve from the importing file’s directory.
~/ and ~ resolve from home; absolute paths used as-is.
Inside fenced code blocks / inline code → left literal (great for documenting @ itself).
Trimming trailing punctuation: @docs/setup.md. → imports docs/setup.md.
Recursion up to 5 hops; cycles skipped; missing target leaves @token in place.

Deeper-directory Files (not auto-loaded)

AGENTS.md files below the current directory are surfaced in a <dir-context> block as pointers only (the agent is told to read them before editing those directories).

2. Sticky Rules (RULES.md)

Behavior: Converted into always-apply rules, re-attached near current turn across long sessions. Survive compaction.

Location	Scope
`~/.omp/agent/RULES.md`	User (all sessions)
`<ancestor>/.omp/RULES.md`	Nearest ancestor wins, walk-up to repo root

Critical: RULES.md is only recognized at native locations. A RULES.md anywhere else is ignored.

# Example: ~/.omp/agent/RULES.md
Never commit or push unless the user explicitly asks.
Do not edit generated files (dist/, .svelte-kit/, node_modules/).
Always run the project formatter before yielding.

Don’t put long background here — that belongs in AGENTS.md. RULES.md is for the handful of non-negotiable requirements.

3. System Prompt Customization

Replace vs. Append

Goal	File	Effect
Keep defaults + add instructions	`APPEND_SYSTEM.md`	Appended after all default blocks
Replace stable instructions, keep project footer	`SYSTEM.md`	Replaces block 0 only; block 1 (project context) preserved
Custom session titles	`TITLE_SYSTEM.md`	Only affects `/new` session naming

Discovery: findConfigFile — checks <cwd>/.omp → <cwd>/.claude → <cwd>/.codex → <cwd>/.gemini, then user-level equivalents. No ancestor walk-up. Must be directly under cwd’s config base or user-level.

# Example: Keep defaults + add rules
# ~/.omp/agent/APPEND_SYSTEM.md
Prefer Bun APIs over Node APIs.
When you change a public function, run `bun check` before yielding.

⚠️ SYSTEM.md / APPEND_SYSTEM.md content is plain text — {{cwd}} and other Handlebars tokens are NOT substituted. Skills/rules/tool guidance is dropped when using SYSTEM.md (use APPEND_SYSTEM.md to keep them).

4. Skills (Optional Capability Packs)

Shape: <root>/skills/<skill-name>/SKILL.md

Provider Priority

Priority	Provider	Locations
100	`native`	`~/.omp/agent/skills/`, `<repo>/.omp/skills/`
90	`omp-plugins`	Extension package `skills/` directories
80	`claude`	`~/.claude/skills/`, `<repo>/.claude/skills/`
70	`claude-plugins`, `agents`, `codex`	Various
55	`opencode`	`~/.opencode/skills/`
30	`github`	`<repo>/.github/skills/`
5	`omp-managed`	`~/.omp/agent/managed-skills/` (auto-learn)

SKILL.md Frontmatter

name: my-skill              # defaults to dir name
description: Required for native/omp-plugins/github
globs: ["**/*.ts"]           # optional file pattern
alwaysApply: true            # optional
hide: true                  # still reachable via skill:// and /skill:
disableModelInvocation: true

Usage

System prompt: lightweight metadata (name + description) listed for model
skill://<name>: on-demand read via tool
skill://<name>/path: read asset within skill directory
/skill:<name> [args]: interactive slash command injection

5. Agents (Custom Subagent Definitions)

Shape: <root>/agents/<agent-name>.md

Providers

Provider	Locations
`native`	`~/.omp/agent/agents/.md`, `<repo>/.omp/agents/.md`
`claude`	`~/.claude/agents/.md`, `<repo>/.claude/agents/.md`
`agents`	`~/.agent/agents/.md`, `<repo>/.agent/agents/.md`

Agents discovered from .claude/agents/*.md are advertised as OMP task subagents.

6. Hooks (Event-Driven Interceptors)

Shape: JS/TS factory function.

// .omp/hooks/pre/tool_call.ts
import type { HookAPI } from "@oh-my-pi/pi-coding-agent/extensibility/hooks";
export default function hook(pi: HookAPI): void {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && String(event.input.command ?? "").includes("rm -rf")) {
      return { block: true, reason: "Blocked by policy" };
    }
  });
}

Hook Events

Event	When	Can Return
`tool_call`	Before tool execution	`{ block?, reason? }`
`tool_result`	After tool execution	`{ content?, details? }`
`session_start`	Session start	—
`session_before_compact`	Before compaction	`{ cancel?, compaction? }`
`session_shutdown`	Session end	—
`before_agent_start`	Before agent starts	`{ message? }`
`turn_start` / `turn_end`	Each turn	`{ message? }`
`context`	Context injection	`{ messages? }`

Hook Capabilities

Register event handlers with pi.on(...)
Send persistent messages with pi.sendMessage(...)
Persist non-LLM state with pi.appendEntry(...)
Register slash commands with pi.registerCommand(...)
Register message renderers with pi.registerMessageRenderer(...)
Run shell commands with pi.exec(...)
Author schemas with pi.zod, pi.typebox

7. Tools (Custom Tool Extensions)

Discovery: .omp/tools/, ~/.omp/agent/tools/, package.json → "omp": { "extensions": [...] }, --extension / -e <path>.

Tools are wrapped by ExtensionToolWrapper and callable by the model with schemas and runtime side effects.

8. Prompts (Custom Prompt Templates)

Location	Scope
`<repo>/.omp/prompts/`	Project
`~/.omp/agent/prompts/`	User

Interactive invocation: /<name> slash command.

9. MCP Servers

Location	Scope
`~/.omp/agent/mcp.json`	User
`<repo>/.omp/.mcp.json`	Project
`~/.claude/settings.json`	Claude compat

{
  "mcpServers": {
    "my-server": { "type": "stdio", "command": "npx", "args": ["-y", "my-mcp"] }
  },
  "disabledServers": ["old-server"]
}

10. Memory (Persistent Session Memory)

Backend	Location	Behavior
`local` (default)	`~/.omp/agent/memory/`	`memory_summary.md` + compressed artifacts per session
`hindsight`	Hindsight server	Retains transcripts every Nth turn, recalls on first turn
`off`	—	No memory subsystem

Memory root: memory://root → project memory summary.

memory://root              → memory_summary.md
memory://root/MEMORY.md    → full memory
memory://root/skills/<name>/SKILL.md  → skill memory

11. Config

Location	Scope	Priority
`~/.omp/agent/config.yml`	User	Higher
`<repo>/.omp/config.yml`	Project	Lower
`--config <yaml>`	CLI overlay	Highest

# Example: ~/.omp/agent/config.yml
modelRoles:
  default: anthropic/claude-sonnet-4-5
  smol: openai/gpt-4.1-mini
  slow: anthropic/claude-opus-4-5:high
 
tools:
  approvalMode: write
  approval:
    bash: prompt
 
compaction:
  strategy: context-full
  thresholdPercent: 80
 
skills:
  enabled: true

12. Load Order & Shadowing (Complete)

┌─────────────────────────────────────────────────────┐
│ 1. CLI flags          (--system-prompt, --config)   │ ← HIGHEST
│ 2. User config        (~/.omp/agent/config.yml)     │
│ 3. Project config     (<repo>/.omp/config.yml)      │
│ 4. Context files      (per provider priority)        │
│    ├─ native user     (~/.omp/agent/AGENTS.md)      │
│    ├─ claude user     (~/.claude/CLAUDE.md)          │
│    ├─ native project  (<repo>/.omp/AGENTS.md)      │
│    ├─ agents-md       (./AGENTS.md walk-up)         │
│    └─ github          (.github/copilot-instructions)│
│ 5. Sticky rules       (~/.omp/agent/RULES.md)       │
│ 6. Skills metadata    (listed in system prompt)      │
│ 7. Tools inventory    (listed in system prompt)      │
│ 8. Project footer     (workstation, tree, date)    │ ← LOWEST
└─────────────────────────────────────────────────────┘

13. Idiot-Proof Workflow

# ═══════════════════════════════════════════════════════════════
# QUICK-START: Add knowledge/context to OMP for this project
# ═══════════════════════════════════════════════════════════════
 
# Step 1: Create project context (auto-loaded every session)
mkdir -p "$HOME/<project>/.omp"
 
cat > "$HOME/<project>/.omp/AGENTS.md" << 'EOF'
# Project: <name>
## Architecture
- Monorepo using pnpm workspaces
- TypeScript strict mode
- Tests via Vitest
 
## Build Commands
pnpm dev        # all dev servers
pnpm build      # workspace build
pnpm test:run   # vitest run
 
## Rules
- Never commit secrets
- Always run the formatter before yielding
- Use pnpm -F <filter> for package-scoped operations
EOF
 
# Step 2: Add non-negotiable sticky rules (survives compaction)
cat > "$HOME/<project>/.omp/RULES.md" << 'EOF'
Never commit or push without explicit user approval.
Never edit generated files (dist/, .svelte-kit/, node_modules/).
EOF
 
# Step 3: Add a skill (optional capability pack)
mkdir -p "$HOME/<project>/.omp/skills/my-skill"
cat > "$HOME/<project>/.omp/skills/my-skill/SKILL.md" << 'EOF'
---
name: my-skill
description: How to work with X in this project
---
 
# My Skill
## When to use
When the user asks about X or Y.
 
## Steps
1. First do this
2. Then do that
3. Verify with `bun check`
EOF
 
# Step 4: Add a hook (optional event interceptor)
mkdir -p "$HOME/<project>/.omp/hooks/pre"
cat > "$HOME/<project>/.omp/hooks/pre/tool_call.ts" << 'EOF'
import type { HookAPI } from "@oh-my-pi/pi-coding-agent/extensibility/hooks";
export default function hook(pi: HookAPI): void {
  pi.on("tool_call", async (event, ctx) => {
    // Block dangerous commands
    if (event.toolName === "bash") {
      const cmd = String(event.input.command ?? "");
      if (cmd.includes("rm -rf") && !ctx.hasUI) {
        return { block: true, reason: "rm -rf blocked in non-interactive mode" };
      }
    }
  });
}
EOF
 
# Step 5: Verify OMP sees your files
cd "$HOME/<project>"
omp --no-context-files   # test without context files
omp                      # test with context files (default)
 
# ═══════════════════════════════════════════════════════════════
# That's it. OMP auto-discovers everything. No flags needed.
# ═══════════════════════════════════════════════════════════════

14. Common Pitfalls

Pitfall	Why It Happens	Fix
`CLAUDE.md` not loaded	OMP only reads it from `<cwd>/.claude/`, not ancestors	Use `.omp/AGENTS.md` instead
`RULES.md` ignored	Not at native location (`~/.omp/agent/` or `<repo>/.omp/`)	Move to `.omp/RULES.md`
Can’t see skill	Missing `description` frontmatter (required for native)	Add `description:` to `SKILL.md`
`SYSTEM.md` drops skills/rules	Replaces block 0 (guidance)	Use `APPEND_SYSTEM.md` to keep defaults
Context file in subdir not loaded	Only nearest `.omp/AGENTS.md` wins per depth	Launch from the right directory or use `@` imports
Hook not firing	Provider disabled or wrong event name	Check `disabledProviders`, verify event name
MCP server not found	Wrong config path	Use `~/.omp/agent/mcp.json` or `.omp/.mcp.json`

15. Provider Disable/Enable

# ~/.omp/agent/config.yml
disabledProviders:
  - claude      # disables ALL claude-discovered items
  - github      # disables ALL github-discovered items
  - path: ~/work/legacy   # scoped disable
    providers:
      - gemini

⚠️ Disabling a discovery provider removes everything from it — MCP servers, skills, hooks, tools, slash commands, not just context files.

16. Symbol Reference

Symbol	Meaning
`<cwd>`	Current working directory OMP launched from
`<repo>`	Git repository root (or `<cwd>` if not a repo)
`<ancestor>`	Any directory between cwd and repo root (native/agents only)
`★`	Highest priority at that scope
`✅`	Ancestor walk-up enabled
`❌`	Fixed location only

moincraft SSOT

Explorer

OMP Cognitive Filesystem — Complete Manifest

OMP Cognitive Filesystem — Complete Manifest

🧠 Quick-Start Cheat Sheet

1. Context Files (Advisory Background)

Provider Priority (highest wins at same depth)

Shadowing Rules

`@` Imports

Deeper-directory Files (not auto-loaded)

2. Sticky Rules (RULES.md)

3. System Prompt Customization

Replace vs. Append

4. Skills (Optional Capability Packs)

Provider Priority

SKILL.md Frontmatter

Usage

5. Agents (Custom Subagent Definitions)

Providers

6. Hooks (Event-Driven Interceptors)

Hook Events

Hook Capabilities

7. Tools (Custom Tool Extensions)

8. Prompts (Custom Prompt Templates)

9. MCP Servers

10. Memory (Persistent Session Memory)

11. Config

12. Load Order & Shadowing (Complete)

13. Idiot-Proof Workflow

14. Common Pitfalls

15. Provider Disable/Enable

16. Symbol Reference

See Also

Graph View

Table of Contents

Backlinks

moincraft SSOT

Explorer

OMP Cognitive Filesystem — Complete Manifest

OMP Cognitive Filesystem — Complete Manifest

🧠 Quick-Start Cheat Sheet

1. Context Files (Advisory Background)

Provider Priority (highest wins at same depth)

Shadowing Rules

@ Imports

Deeper-directory Files (not auto-loaded)

2. Sticky Rules (RULES.md)

3. System Prompt Customization

Replace vs. Append

4. Skills (Optional Capability Packs)

Provider Priority

SKILL.md Frontmatter

Usage

5. Agents (Custom Subagent Definitions)

Providers

6. Hooks (Event-Driven Interceptors)

Hook Events

Hook Capabilities

7. Tools (Custom Tool Extensions)

8. Prompts (Custom Prompt Templates)

9. MCP Servers

10. Memory (Persistent Session Memory)

11. Config

12. Load Order & Shadowing (Complete)

13. Idiot-Proof Workflow

14. Common Pitfalls

15. Provider Disable/Enable

16. Symbol Reference

See Also

Graph View

Table of Contents

Backlinks

`@` Imports