Metadata-Version: 2.4
Name: p-layers
Version: 0.1.4
Summary: 7 governance layers for AI agent memory — P0-P6 with KnowledgeDB, MCP server, and wiki-compile
Project-URL: Home, https://github.com/humanerd-drew/p-layer
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2.0,>=1.0
Provides-Extra: pg
Requires-Dist: psycopg2-binary>=2.9; extra == "pg"
Requires-Dist: pgvector>=0.3; extra == "pg"
Requires-Dist: numpy>=1.24; extra == "pg"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# P-Layer

**7 layers. 1 memory. Zero chaos.**

[**한국어**](./README.ko.md)

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.

## Quick Start — Your Own Database

```bash
pip install p-layers
```

### SQLite mode (zero config, single user)

```bash
# Initialize
p-layer-init --init
# or: python3 -m p_layer --init

# Start MCP server
p-layer-mcp
# or: python3 -m p_layer --serve
```

### PostgreSQL mode (multi-agent, vector search)

```bash
pip install p-layers[pg]

# Point at your PostgreSQL DB
export KNOWLEDGE_PG_DSN="dbname=your_knowledge_db host=localhost user=me"

# Initialize the schema
python3 -m p_layer --init-pg "$KNOWLEDGE_PG_DSN"

# Start MCP server
p-layer-mcp
```

### Verify it works

```python
from p_layer.core.db import KnowledgeDB

db = KnowledgeDB()
db.insert(layer="P5", type="fact",
          content="My first fact in my own database.",
          who="system:quickstart")
results = db.search("first fact", limit=5)
print(f"Found {len(results)} results")
db.close()
```

### Check status

```bash
python3 -m p_layer --status
# → { "mode": "sqlite", "pg_available": false, "write_test": "PASS", ... }
```

### What's in your database

The DB is created at `$KNOWLEDGE_DB_DIR/knowledge.db` (default: `./.knowledge/knowledge.db`) in SQLite mode. For PostgreSQL, use the DSN you provided.

```
.knowledge/
└── knowledge.db          ← all your facts, decisions, patterns, incidents
    ├── memory table       ← the content (with FTS5 full-text search)
    ├── entities table     ← your ontology nodes (24 types)
    └── relations table    ← edges between entities (depends_on, fixed_by, ...)
```

## The 7 Layers

| Layer | Name | Purpose | Query | Write Access |
|-------|------|---------|-------|-------------|
| **P0** | brainstem | Immutable rules | Every session start | system only |
| **P1** | limbic | Identity & persona | Session start + output | human only |
| **P2** | hippocampus | Raw session archive | **Last resort** | append-only |
| **P3** | sensors | Tool integrations | When debugging | system + cron |
| **P4** | cortex | Skills & growth | Skill selection | agent + manual |
| **P5** | ego | **Compiled wiki** | **1st priority** | auto-generated |
| **P6** | prefrontal | Incidents & RCA | During RCA | agent + manual |

## 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:

| Tool | What it does |
|------|-------------|
| `knowledge_remember` | Store a fact with confidence, TTL, version label |
| `knowledge_recall` | Ranked search — confidence + freshness + 5% serendipity |
| `knowledge_forget` | Soft-delete (supersede, never destroy) |
| `knowledge_update` | Update by ID — old version is superseded, history preserved |
| `knowledge_memory-stats` | Entry counts by layer |
| `knowledge_snapshot-create` | Freeze current state under a version label |
| `knowledge_snapshot-rollback` | Supersede entries created after a snapshot |

### MCP client configuration

**opencode** (`opencode.jsonc`):
```json
{
  "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`):
```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

| Variable | Effect |
|----------|--------|
| `KNOWLEDGE_PG_DSN` unset | SQLite mode (`.knowledge/knowledge.db`) |
| `KNOWLEDGE_PG_DSN=dbname=...` | PostgreSQL primary, SQLite fallback |
| `KNOWLEDGE_DB_DIR=/path` | Custom SQLite directory |

## 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

| Script | Purpose |
|--------|---------|
| `scripts/ontology_setup.py` | Initialize entity type hierarchy + relation constraints |
| `scripts/seed_knowledge_db.py` | Bootstrap knowledge.db with schema + seeds |
| `scripts/ingest_fact.py` | Insert a single fact from CLI |
| `scripts/ingest_instructions.py` | Batch-ingest .md files into KnowledgeDB |
| `scripts/inference.py` | Transitive closure, backtrace, contradiction detection |
| `scripts/wiki_compile.py` | KnowledgeDB → Markdown wiki pages + INDEX.json |
| `scripts/wiki_lint.py` | Broken link detection, INDEX consistency |

## 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:

| Relation | Source → Target |
|----------|----------------|
| `depends_on` | any → tool/script/skill |
| `fixed_by` | incident → pattern/decision |
| `caused` | decision/pattern → incident |
| `led_to` | decision → decision |
| `cites` | paper → paper |
| `contradicts` | decision/pattern → decision/pattern |

## License

MIT


