p-layer

p-layer

Memory for AI agents with rules that are kept, not just written.

🌏 README.ko.md — 한국어

Demo

Agent conversation

The agent remembers across sessions (recall), and when it tries to change a rule the system refuses until a human approves — then it's applied and audited.

Memory health report (real data)

A weekly health report: is the memory actually being distilled? Are rules alive? Are there silent failures? (Real numbers from a production agent stack.)

AI assistants today are brilliant and forgetful. When a conversation ends, what was decided in it — which payment system you switched to, how a client prefers to be contacted, what actually fixed a bug — ends with it. The next session starts from zero. And when an agent does keep notes, there is no control: anyone can write anything, rules are suggestions, and nothing is ever traced.

p-layer gives an agent a memory that works like a well-run organization instead of a junk drawer:

• it remembers across sessions and finds what you need even weeks later,
• it is organized in layers with clear jobs — from rules that must never change, to incident reports,
• it enforces its own rules — the system refuses and records a write that isn't allowed, instead of trusting a prompt,
• it never destroys — old versions are superseded, and the full history stays,
• and it puts everything on the record — every write, every refused write, is audited.

It is small, has zero dependencies, speaks the standard connector (MCP) that Claude, opencode, and Cursor already use, and runs on your own machine.

---

The problem this is trying to solve

Agents are amnesiacs. A chatbot or coding agent only "remembers" what is in the current window. Ask it next week about the decision it made today and it will guess. The first fix for this is a memory store — a place where facts survive. That part is easy.

The hard part is control. Once an agent can write to a long-term memory, three things go wrong:

1. Anyone can write anything. A stray thought gets saved as if it were a company rule, and nobody can tell the difference.
2. Rules are only suggestions. "Never change the pricing policy" lives in a text file and is hoped to be followed, not enforced. The agent that is supposed to obey it is also the one that can edit it.
3. Everything accumulates, nothing is organized. Raw session logs pile up forever. Finding "the time we fixed the payment bug" means searching through everything.

p-layer is the answer to those three failures: rules first, retrieval second.

---

The design direction — five principles

1. Memory is organized in layers, like a brain or an org chart

Every piece of memory belongs to one of seven layers. Each layer has a job and rules about who may touch it:

Layer	What lives there	Plain-language purpose	Who may write
P0	Rules	The constitution. "Never expose secrets." Must not change.	only the system
P1	Identity & persona	Who the agent is, how it speaks.	only the system
P2	Raw sessions	Everything that happened, kept as-is.	system, gateways, cron
P3	Tool integrations	What the agent can plug into.	system, gateways, cron
P4	Skills & growth	What the agent has learned to do.	system, agent, human
P5	Compiled knowledge	Distilled insights — the first place to look.	system, agent, tools
P6	Incidents & fixes	What broke, why, and what fixed it.	system, agent, human

Lower layers are higher authority: a P0 rule wins over a P1 preference, without negotiation.

2. Rules are enforced by the system, not by asking nicely

When an agent tries to write to a layer it is not allowed to touch, the write is refused with an error, and the refusal itself is recorded. The rule is not a suggestion in a text file — it is a permission the system checks on every write.

3. Memory is never destroyed — it is superseded

There is no delete button that erases history. "Forgetting" marks an entry as superseded: it stops showing up in searches, but the record of it — and of what replaced it — remains. This is version control applied to memory.

4. Everything is on the record

An audit log records every write and every refused write: who did it, to which layer, when, and why. If something wrong ever lands in memory, you can see exactly how it got there — and roll the memory back to a snapshot from before it happened.

5. Memory organizes itself

Raw notes are fine for a while; they are not fine forever. p-layer runs maintenance the way a good organization does:

• Consolidation — batches of raw session notes are distilled into short insights (the messy P2 becomes useful P5).
• A compiled wiki — active knowledge is rendered into clean, per-layer pages with their origin story attached.
• Snapshots — you can freeze the memory at a point in time and roll back to it.
• Re-embedding — when the underlying understanding model changes, memory is re-indexed in the background instead of breaking.

One method, two homes

The same memory, with the same rules, runs in two places:

• SQLite — a single file on your machine. Perfect for one personal agent.
• PostgreSQL — a shared database. For a team or a small business where several agents (or people) use one memory.

The rules, layers, and behavior are identical in both; the same test suite verifies both so they cannot drift apart.

---

How it works — one story

Suppose your AI assistant is maintaining a small shop's payment system.

1. P6 — the incident. The assistant discovers a payment bug. It writes an incident report: what happened, timeline, and its first guess at a root cause.
2. P0 — the rule check. The root cause turns out to be a rule violation. The assistant proposes a rule amendment; only the system can actually change P0.
3. The knowledge graph. The incident is linked to the payment tool and to the fix pattern it depends on. "What is related to this payment bug?" is now answerable by walking those links — a root-cause analysis.
4. Weeks later — recall. A similar symptom appears. The assistant searches memory and the old incident surfaces, ranked by relevance and how certain it was — before the same mistake is repeated.
5. Nightly — consolidation. The session's raw notes are distilled into a durable insight and added to the compiled knowledge.
6. The same bug never happens twice — not because the agent is smarter, but because the organization of its memory remembered.

---

Proof it works

The eval harness (p_layer eval <suite.json>) runs the same data through two engines — the drewgent baseline (a reconstruction of its searchKnowledge: quote-stripped OR-join FTS5) and p-layer (hybrid FTS5 + semantic, RRF-fused) — and reports recall@k for both, plus ACL compliance:

python3 -m p_layer eval examples/suite.example.json

Retrieval scores depend on your data and embedder, so this page does not hard-code them; benchmarks/real_data_bench.py measures recall@k / MRR on a real memory archive. What is deterministic is the governance: p-layer ranks by how certain the memory was and how fresh it is, not just by word matching, and all 30 (layer, who) permission cases (every layer × every writer) are enforced by the system (pass_rate: 1.0) with every denied write recorded in the audit log.

---

Try it in two minutes

pip install p-layers
p-layer --db ~/.p_layer/memory.db --embed hash init
p-layer --db ~/.p_layer/memory.db --embed hash status

p-layer --db ~/.p_layer/memory.db --embed hash remember "we switched to PortOne v2 for payments" --type decision --source onboarding
p-layer --db ~/.p_layer/memory.db --embed hash recall "payment" --why
p-layer --db ~/.p_layer/memory.db --embed hash context "current payment task"
p-layer --db ~/.p_layer/memory.db --embed hash doctor

init creates the store and prints the next commands. status is safe to run before initialization; doctor checks the schema, integrity, FTS index, and embedding configuration. Call context once at session start to retrieve task-relevant memory and place canonical rules first within the budget. Add --why to recall to see each result's source, session, and creation time. No separate database or service is required; the memory is one file.

Use it with your AI tools

Agents talk to memory through MCP, the standard connector. Add one block to your tool's config and the agent can remember, recall, audit, snapshot, and trace root causes:

At the start of a task, call context with the current user request; it returns relevant memories and canonical rules in one bounded payload.

{
  "mcp": {
    "p-layer": {
      "type": "local",
      "command": ["python3", "-m", "p_layer", "serve"],
      "env": { "P_LAYER_DB": "~/.p_layer/memory.db" }
    }
  }
}

---

For developers — the technical shape

• Engine: p_layer.store.Store — SQLite + FTS5 + pluggable embeddings, forward-only checksummed migrations. One schema, one implementation.
• Governance: P0-P6 layer ACLs enforced at write time (WriteDenied), supersede-not-delete, snapshots/rollback, full audit log, contradiction scan.
• Recall: hybrid FTS5 + semantic, RRF fusion, additive rerank (confidence + recency + TTL boosts), superseded excluded, type-diversified.
• Graph: typed entity/relation ontology with constraint validation, explore / trace / root-cause analysis / transitive closure (cycle-safe).
• Ops jobs: reembed (versioned vector backfill), consolidate (episodic → semantic digests), compile-wiki (P5 pages). SQLite-only; on PostgreSQL they raise loudly rather than silently degrade.
• Governance & drift (0.7.0): gate (P0 ontology review gate — propose → approve → apply/deprecate, human approval required, idempotent, JSONL validation) and drift-report (weekly baseline comparison over knowledge/episodes/entities/gate state; read-only, distinguishes no-change from failure).
• PostgreSQL: p_layer.pgstore.PgStore — same interface and behavior, verified by a shared parity suite (pg_trgm ILIKE for CJK, pgvector optional).
• MCP server: 14 tools, including query-aware startup context, with a zero-dependency stdio implementation verified end-to-end by wire-level tests (and against the official SDK in CI).
• Migration from legacy agent memory: already running an agent memory store? import-drewgent copies a legacy knowledge.db (knowledge/entities/relations/sessions) into p_layer, and p_layer.drewdb can even open it in place under p_layer's governance (WAL, busy timeout) so your existing tools keep working while p_layer takes over the connection. import-rules / import-incidents bring your existing rule and incident files in. You migrate when you're ready — nothing is locked in.
• Tests: 167 — SQLite + PostgreSQL parity, governance, graph, ops, MCP wire, packaging, FTS5 query sanitization regressions, additive rerank, and CLI UX/context.
• PyPI: p-layers · GitHub: p-layer · package: p_layer · console: p-layer

python3 -m unittest discover -s tests -v   # no dependencies, no network

Additive Rerank (0.8.0)

Retrieval scoring was redesigned from multiplicative to additive: raw RRF relevance is preserved as the baseline, with small bounded boosts layered on top for confidence, recency, and TTL freshness. This matters because:

• In the old multiplicative scheme (rrf × confidence × freshness), a single zero-signal killed an entry's entire score.
• The additive scheme keeps signals independent — a low-confidence entry that perfectly matches the query still surfaces.

How it works

rerank_score = raw_rrf + confidence_boost + recency_boost + ttl_boost

Signal	What it does	Default constants
confidence_boost	Entries above confidence_center get a nudge up; below get pushed down	gain=0.0005, center=0.5
recency_boost	Entries within recency_window_days get a boost that decays linearly to 0	gain=0.0002, window=30 days
ttl_boost	Entries with a TTL that are still "fresh" get a boost (replaces old _freshness multiplier)	uses recency_gain scale

All boosts are intentionally tiny relative to RRF scores (~0.016) — they nudge tie-breaking, not override relevance.

Configuring

from p_layer import Store, RerankConfig

# Custom configuration
config = RerankConfig(
    confidence_gain=0.001,       # more aggressive confidence signal
    confidence_center=0.6,       # raise the bar
    recency_gain=0.0005,         # stronger recency preference
    recency_window_days=7.0,     # only last week matters
)

# Per-call override (advanced — most users just set module default)
from p_layer.store import rrf_fuse
results = rrf_fuse(fts_results, sem_results, limit=10, row_lookup=lookup, rerank=config)

# Disable rerank entirely (legacy multiplicative behavior)
results = rrf_fuse(fts_results, sem_results, limit=10, row_lookup=lookup,
                   rerank=RerankConfig(enabled=False))

Results include a rerank_components dict for debugging:

{
  "score": 0.016734,
  "rrf": 0.0164,
  "rerank_components": {
    "rrf": 0.0164,
    "confidence_boost": 0.00025,
    "recency_boost": 0.000134,
    "ttl_boost": 0.0
  }
}

Legacy mode

Pass RerankConfig(enabled=False) to get the old rrf × (0.5 + 0.5 × confidence) × freshness scoring. Results will not include rerank_components.

---

Credits

Built as a production-grade rebuild of the P0-P6 vault concept from opencode-drewgent, with orchestration conventions from Gajae-Code.

License

MIT

Links

• Author: humanerd (휴머너드) — building AI agent systems, automation pipelines, and the record of breaking & fixing both.
• Blog: humanerd.kr — agent systems, GEO/SEO engineering, build logs.