How humanerd-drew/p-layer works
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: store.py SQLite Store · cli.py CLI workflows · mcp.py MCP stdio server · embed.py Embedding providers
Components 17
Entry Points
- CLI workflows · Routes remember, recall, import, evaluation, and maintenance commands.
p_layer/cli.py - Package entry point
p_layer/__main__.py - MCP stdio server · Exposes memory operations to agent clients.
p_layer/mcp.py
Storage & Governance
- SQLite Store · Primary schema-backed memory, audit, snapshot, and graph store.
p_layer/store.py - Write admission & history · Enforces P0–P6 writer ACLs, records rejections, and supersedes records.
p_layer/store.py - Schema migrations · Applies forward-only checksummed migrations.
p_layer/migrations.py - PostgreSQL Store · Alternative Store contract with optional pgvector and pg_trgm.
p_layer/pgstore.py - Ontology gate & drift · Manages rule proposal, approval, application, deprecation, and drift reports.
p_layer/gate.py
Recall & Operations
- Embedding providers · Provides offline hash and Ollama-backed vectors.
p_layer/embed.py - Hybrid recall · Fuses FTS and vector candidates, then ranks by confidence and freshness.
p_layer/store.py - Knowledge graph · Validates typed entities and relations and supports cycle-safe traversal.
p_layer/store.py - Memory maintenance · Re-embeds vectors, consolidates P2 into P5, and compiles knowledge pages.
p_layer/store.py - Recall & ACL evaluation · Compares baseline and hybrid recall while checking ACL compliance.
p_layer/eval.py
Compatibility
- Drewgent importer · Imports legacy knowledge databases and vault-originated rules or incidents.
p_layer/import_drewgent.py - drew.db adapter · Manages existing drew.db-style SQLite connections compatibly.
p_layer/drewdb.py - DB compatibility adapters
p_layer/compat/db.py - MCP compatibility adapters
p_layer/compat/mcp.py
Connections 19
- 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