P-Layer

7 layers. 1 memory. Zero chaos.

Organize your AI agent's memory into governance layers — from immutable rules (P0) to incident retrospectives (P6). Each layer has a contract: who can write, when to query, how to maintain.

pip install p-layers          # repo: p-layer, PyPI: p-layers, import: p_layer
python3 -m p_layer.mcp.server  # starts MCP server with SQLite (zero config)

The 7 Layers

Real-world flow

An AI assistant discovers a bug in the build pipeline:

1. P6 — Writes an incident report with timeline + root cause
2. P0 — If the root cause was a rule violation, proposes a P0 amendment
3. knowledge_recall — When similar symptoms appear weeks later, the MCP server surfaces the incident ranked by confidence + freshness + serendipity
4. wiki_compile.py — End of day, all incidents + fixes are compiled into P5 wiki pages
5. Query routing — Next session, the compiled knowledge is found instantly (P5 first, P2 last)

The same bug never happens twice — not because the agent remembers, but because the governance layer learned.

MCP Server

7 tools, all included:

MCP client configuration

opencode (opencode.jsonc):

{
  "mcp": {
    "p-layer": {
      "type": "local",
      "command": ["python3", "-m", "p_layer.mcp.server"],
      "env": { "KNOWLEDGE_PG_DSN": "{env:KNOWLEDGE_PG_DSN}" },
      "enabled": true
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "p-layer": {
      "command": "python3",
      "args": ["-m", "p_layer.mcp.server"],
      "env": { "KNOWLEDGE_PG_DSN": "" }
    }
  }
}

Architecture

P0-brainstem (rules) ─────────── governs all layer write permissions
P1-limbic (persona) ──────────── defines agent voice
                                        │
P2-hippocampus (raw data) ──────────────┤
  │                                      │
  ├──→ sessions/ (append-only logs)      │
  ├──→ memories/ (extracted entries)     │
  └──→ knowledge/ (ingested artifacts)   │
                                          ▼
P3-sensors ──→ MCP configs ──→    P_LAYER KNOWLEDGEDB   ←── P4-cortex skill index
                                    (Pg + SQLite)                  │
                                          │                        │
               ┌──────────────────────────┤                        │
               ▼                          ▼                        ▼
     knowledge_recall           P5-ego/wiki/compiled/      P6-prefrontal
     (ranked FTS + vector)      (auto-generated daily)     (incidents + RCA)
                                     │
                               wiki_lint.py
                               (broken link check)

Backend selection

Query Routing (priority order)

When an agent searches for information:

1. P5-ego/wiki/compiled/       ← compiled wiki (check FIRST)
2. P5-ego/memory/               ← saved preferences
3. P2-hippocampus/knowledge/    ← raw ingested knowledge
4. P2-hippocampus/memories/     ← raw session memory
5. P2-hippocampus/sessions/     ← raw session logs (LAST resort)
6. KnowledgeDB (SQLite/Pg)      ← cross-cut fallback

Steps 1-2 should cover ~80% of queries. Steps 3+ are gaps → next wiki-compile cycle.

Using p-layers in your project

The p-layers/ directory contains the canonical governance contracts. Each map to a runtime directory in your project:

your-project/
├── p-layers/               ← contract docs (canonical, read-only)
│   ├── P0-brainstem/README.md
│   └── ...
├── P2-hippocampus/         ← runtime data (your sessions, archives)
│   └── sessions/
├── P5-ego/
│   └── wiki/compiled/      ← auto-generated by wiki_compile.py
└── P6-prefrontal/
    └── incidents/          ← your incident reports

Copy → cp -r p-layers/ your-project/ (you own them, customize freely)
Submodule → git submodule add <url> (stay in sync)
Refer → point your agent's init workflow at p-layers/P0-brainstem/README.md

Scripts

Ontology Layer

24 entity types across 6 root categories:

artifact    → doc, code, project
agent       → persona, tool, script, skill
decision    → pattern, preference
event       → incident, session
knowledge   → concept, paper, reference
meta        → category, _task, fact

Relation constraints enforce type safety at insert time:

License

MIT