# humanerd-drew/p-layer architecture

> Architecture diagram of the GitHub repository humanerd-drew/p-layer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/humanerd-drew/p-layer
- Repository: https://github.com/humanerd-drew/p-layer

## Overview

#### Purpose and entry points
p-layer is a governed long-term memory system for AI agents. It persists layered memories, enforces writer ACLs, retains history through supersession, and exposes retrieval and management through CLI and MCP. Primary entry points are `p_layer/__main__.py`, `p_layer/cli.py`, and the stdio MCP server in `p_layer/mcp.py`.

#### Core storage and portability
`p_layer/store.py` defines the primary SQLite-backed `Store`: schema-backed memory, FTS5 retrieval, audit history, snapshots, graph data, and maintenance operations. `p_layer/migrations.py` owns forward-only checksummed schema migrations. `p_layer/pgstore.py` provides `PgStore`, intended to preserve the same behavioral contract on PostgreSQL, with optional pgvector and pg_trgm-based matching.

#### Governance and immutable history
Write admission is a central boundary: layer P0–P6 permissions are checked before persistence, with rejected writes recorded rather than silently discarded. Supersession replaces destructive deletion, while audit and snapshot/rollback capabilities preserve traceability. This policy layer is concentrated in `p_layer/store.py`; ontology-rule proposal, approval, application, and deprecation are handled by `p_layer/gate.py`.

#### Recall and embedding pipeline
Recall combines SQLite full-text search and semantic vector similarity, fuses candidates, then adjusts ranking for confidence and freshness while excluding superseded records. Embedding providers and vector generation are abstracted in `p_layer/embed.py`; evaluation of baseline versus hybrid recall and ACL compliance is in `p_layer/eval.py`. Offline hash embeddings and Ollama-backed embeddings are material runtime choices.

#### Knowledge graph and operational maintenance
The store supports typed entities and relations with validation, traversal, root-cause tracing, and cycle-safe transitive exploration. Operational stages include re-embedding versioned vectors, consolidating episodic P2 memory into P5 knowledge, and compiling wiki-like knowledge pages; these SQLite-specific operations live in `p_layer/store.py`. Drift reporting over knowledge, episodes, entities, and gate state is implemented in `p_layer/gate.py`.

#### Agent integration boundary
`p_layer/mcp.py` exposes memory operations as a zero-dependency MCP stdio server for clients such as Claude, Cursor, and opencode. The CLI routes human and automation workflows—remember, recall, assemble, serve, import, evaluation, and maintenance—to the store implementation via `p_layer/cli.py`.

#### Migration and compatibility adapters
`p_layer/import_drewgent.py` imports legacy drewgent knowledge databases and vault-originated rules/incidents into governed storage. `p_layer/drewdb.py` instead opens and manages an existing drew.db-style SQLite database connection while preserving legacy schema/tool compatibility. Compatibility-facing adapters are grouped in `p_layer/compat/db.py` and `p_layer/compat/mcp.py`.

Main entry points: [`p_layer/store.py`](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/store.py) (SQLite Store), [`p_layer/cli.py`](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/cli.py) (CLI workflows), [`p_layer/mcp.py`](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/mcp.py) (MCP stdio server), [`p_layer/embed.py`](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/embed.py) (Embedding providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Entry Points"]
  node_cli["CLI workflows<br/>[cli.py]"]
  node_main["Package entry point<br/>Python entry<br/>[__main__.py]"]
  node_mcp["MCP stdio server<br/>MCP server<br/>[mcp.py]"]
end

subgraph group_storage["Storage &amp; Governance"]
  node_store[("SQLite Store<br/>storage core<br/>[store.py]")]
  node_write_policy["Write admission &amp; history<br/>governance layer<br/>[store.py]"]
  node_migrations["Schema migrations<br/>migration manager<br/>[migrations.py]"]
  node_pgstore[("PostgreSQL Store<br/>storage backend<br/>[pgstore.py]")]
  node_gate["Ontology gate &amp; drift<br/>policy workflow<br/>[gate.py]"]
end

subgraph group_retrieval["Recall &amp; Operations"]
  node_embedding["Embedding providers<br/>embedding abstraction<br/>[embed.py]"]
  node_recall["Hybrid recall<br/>retrieval pipeline<br/>[store.py]"]
  node_knowledge_graph["Knowledge graph<br/>graph layer<br/>[store.py]"]
  node_maintenance["Memory maintenance<br/>operational pipeline<br/>[store.py]"]
  node_evaluation["Recall &amp; ACL evaluation<br/>evaluation suite<br/>[eval.py]"]
end

subgraph group_compatibility["Compatibility"]
  node_legacy_import["Drewgent importer<br/>migration adapter<br/>[import_drewgent.py]"]
  node_drewdb["drew.db adapter<br/>legacy database adapter<br/>[drewdb.py]"]
  node_compat_db["DB compatibility adapters<br/>compatibility layer<br/>[db.py]"]
  node_compat_mcp["MCP compatibility adapters<br/>compatibility layer<br/>[mcp.py]"]
end

node_main -->|"launches"| node_cli
node_cli -->|"uses"| node_store
node_mcp -->|"serves operations through"| node_store
node_cli -->|"serve command"| node_mcp
node_store -->|"admits writes via"| node_write_policy
node_write_policy -->|"applies governed rules"| node_gate
node_migrations -->|"evolves schema"| node_store
node_pgstore -.->|"preserves contract of"| node_store
node_embedding -->|"generates query vectors"| node_recall
node_store -->|"provides FTS and memory records"| node_recall
node_store -->|"persists entities and relations"| node_knowledge_graph
node_store -->|"runs SQLite operations"| node_maintenance
node_embedding -->|"re-embedding"| node_maintenance
node_evaluation -->|"evaluates"| node_recall
node_evaluation -->|"checks ACL compliance"| node_write_policy
node_legacy_import -->|"imports into"| node_store
node_drewdb -.->|"legacy access support"| node_compat_db
node_compat_db -.->|"compatibility boundary"| node_store
node_compat_mcp -.->|"compatibility boundary"| node_mcp

click node_cli "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/cli.py"
click node_main "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/__main__.py"
click node_mcp "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/mcp.py"
click node_store "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/store.py"
click node_write_policy "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/store.py"
click node_migrations "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/migrations.py"
click node_pgstore "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/pgstore.py"
click node_gate "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/gate.py"
click node_embedding "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/embed.py"
click node_recall "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/store.py"
click node_knowledge_graph "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/store.py"
click node_maintenance "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/store.py"
click node_evaluation "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/eval.py"
click node_legacy_import "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/import_drewgent.py"
click node_drewdb "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/drewdb.py"
click node_compat_db "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/compat/db.py"
click node_compat_mcp "https://github.com/humanerd-drew/p-layer/blob/main/p_layer/compat/mcp.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_main,node_mcp toneBlue
class node_store,node_write_policy,node_migrations,node_pgstore,node_gate toneAmber
class node_embedding,node_recall,node_knowledge_graph,node_maintenance,node_evaluation toneMint
class node_legacy_import,node_drewdb,node_compat_db,node_compat_mcp toneRose
```

## Components

### Entry Points

- [CLI workflows](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/cli.py): CLI · Routes remember, recall, import, evaluation, and maintenance commands. · `p_layer/cli.py`
- [Package entry point](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/__main__.py): Python entry · `p_layer/__main__.py`
- [MCP stdio server](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/mcp.py): MCP server · Exposes memory operations to agent clients. · `p_layer/mcp.py`

### Storage & Governance

- [SQLite Store](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/store.py): storage core · Primary schema-backed memory, audit, snapshot, and graph store. · `p_layer/store.py`
- [Write admission & history](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/store.py): governance layer · Enforces P0–P6 writer ACLs, records rejections, and supersedes records. · `p_layer/store.py`
- [Schema migrations](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/migrations.py): migration manager · Applies forward-only checksummed migrations. · `p_layer/migrations.py`
- [PostgreSQL Store](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/pgstore.py): storage backend · Alternative Store contract with optional pgvector and pg_trgm. · `p_layer/pgstore.py`
- [Ontology gate & drift](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/gate.py): policy workflow · Manages rule proposal, approval, application, deprecation, and drift reports. · `p_layer/gate.py`

### Recall & Operations

- [Embedding providers](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/embed.py): embedding abstraction · Provides offline hash and Ollama-backed vectors. · `p_layer/embed.py`
- [Hybrid recall](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/store.py): retrieval pipeline · Fuses FTS and vector candidates, then ranks by confidence and freshness. · `p_layer/store.py`
- [Knowledge graph](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/store.py): graph layer · Validates typed entities and relations and supports cycle-safe traversal. · `p_layer/store.py`
- [Memory maintenance](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/store.py): operational pipeline · Re-embeds vectors, consolidates P2 into P5, and compiles knowledge pages. · `p_layer/store.py`
- [Recall & ACL evaluation](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/eval.py): evaluation suite · Compares baseline and hybrid recall while checking ACL compliance. · `p_layer/eval.py`

### Compatibility

- [Drewgent importer](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/import_drewgent.py): migration adapter · Imports legacy knowledge databases and vault-originated rules or incidents. · `p_layer/import_drewgent.py`
- [drew.db adapter](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/drewdb.py): legacy database adapter · Manages existing drew.db-style SQLite connections compatibly. · `p_layer/drewdb.py`
- [DB compatibility adapters](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/compat/db.py): compatibility layer · `p_layer/compat/db.py`
- [MCP compatibility adapters](https://github.com/humanerd-drew/p-layer/blob/main/p_layer/compat/mcp.py): compatibility layer · `p_layer/compat/mcp.py`

## Connections

- Package entry point → CLI workflows: launches
- CLI workflows → SQLite Store: uses
- MCP stdio server → SQLite Store: serves operations through
- CLI workflows → MCP stdio server: serve command
- SQLite Store → Write admission & history: admits writes via
- Write admission & history → Ontology gate & drift: applies governed rules
- Schema migrations → SQLite Store: evolves schema
- PostgreSQL Store → SQLite Store: preserves contract of
- Embedding providers → Hybrid recall: generates query vectors
- SQLite Store → Hybrid recall: provides FTS and memory records
- SQLite Store → Knowledge graph: persists entities and relations
- SQLite Store → Memory maintenance: runs SQLite operations
- Embedding providers → Memory maintenance: re-embedding
- Recall & ACL evaluation → Hybrid recall: evaluates
- Recall & ACL evaluation → Write admission & history: checks ACL compliance
- Drewgent importer → SQLite Store: imports into
- drew.db adapter → DB compatibility adapters: legacy access support
- DB compatibility adapters → SQLite Store: compatibility boundary
- MCP compatibility adapters → MCP stdio server: compatibility boundary