p-layers 0.1.0__tar.gz

p_layers-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 humanerd-drew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

p_layers-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: p-layers
+Version: 0.1.0
+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
+License-File: LICENSE
+Requires-Dist: mcp>=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"
+Dynamic: license-file

p_layers-0.1.0/README.md

@@ -0,0 +1,185 @@
+# 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.
+
+```python
+pip install p-layers          # PyPI: p-layers, import: p_layer
+python3 -m p_layer.mcp.server  # starts MCP server with SQLite (zero config)
+```
+
+## 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

p_layers-0.1.0/p_layer/__init__.py

@@ -0,0 +1 @@
+"""p-layer — Knowledge governance layers for AI agents."""

p_layers-0.1.0/p_layer/core/__init__.py

@@ -0,0 +1,5 @@
+"""p-layer core — KnowledgeDB with PostgreSQL (primary) + SQLite (fallback)."""
+
+from .db import KnowledgeDB as KnowledgeDB
+from .memory import recall_ranked as recall_ranked
+from .ontology import ONTOLOGY as ONTOLOGY

p_layers-0.1.0/p_layer/core/db.py

@@ -0,0 +1,412 @@
+"""
+KnowledgeDB — Unified PgVector + SQLite fallback access.
+
+Single entry point for all database operations.
+Layer-aware: P0 (rules) through P6 (incidents).
+
+Usage:
+    db = KnowledgeDB()
+    db.insert(layer='P5', type='knowledge', content='...')
+    results = db.search('query string', layers=['P5', 'P6'])
+"""
+
+import hashlib
+import json
+import logging
+import os
+import sqlite3
+import time
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+try:
+    import numpy as np
+    import psycopg2
+    from pgvector.psycopg2 import register_vector
+    HAS_PG = True
+except ImportError:
+    np = None
+    psycopg2 = None
+    register_vector = None
+    HAS_PG = False
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_DB_DIR = os.environ.get("KNOWLEDGE_DB_DIR", str(Path.cwd() / ".knowledge"))
+PG_DSN = os.environ.get("KNOWLEDGE_PG_DSN", "")
+
+LAYER_AUTHORITY = {
+    "P0": 100, "P1": 80, "P2": 60, "P3": 50, "P4": 40, "P5": 30, "P6": 20,
+}
+
+LAYER_WRITERS = {
+    "P0": frozenset({"system"}),
+    "P1": frozenset({"system"}),
+    "P2": frozenset({"system", "gateway", "cron"}),
+    "P3": frozenset({"system", "gateway", "cron"}),
+    "P4": frozenset({"system", "cron", "agent", "manual"}),
+    "P5": frozenset({"system", "cron", "agent", "manual", "tool"}),
+    "P6": frozenset({"system", "cron", "agent", "manual", "tool"}),
+}
+
+
+class DatabaseError(Exception):
+    pass
+
+
+class WriteDenied(DatabaseError):
+    pass
+
+
+class ConnectionError(DatabaseError):
+    pass
+
+
+class KnowledgeDB:
+    """Unified database access with Pg primary + SQLite fallback."""
+
+    def __init__(self, mode: str = "auto", dsn: str = None,
+                 db_dir: str = None):
+        self.mode = mode
+        self.dsn = dsn or PG_DSN
+        self.db_dir = Path(db_dir or DEFAULT_DB_DIR)
+        self._pg_conn = None
+        self._sqlite_conn = None
+        if HAS_PG:
+            self._connect_pg()
+
+    def _connect_pg(self):
+        if self.mode == "sqlite" or not self.dsn:
+            return
+        try:
+            conn = psycopg2.connect(self.dsn)
+            conn.set_session(autocommit=True)
+            register_vector(conn)
+            self._pg_conn = conn
+        except Exception as e:
+            if self.mode == "pg":
+                raise ConnectionError(f"Pg connection failed: {e}")
+            logger.warning("Pg unavailable, using SQLite fallback: %s", e)
+            self.mode = "sqlite"
+
+    def _connect_sqlite(self):
+        if self._sqlite_conn is None:
+            path = self.db_dir / "knowledge.db"
+            path.parent.mkdir(parents=True, exist_ok=True)
+            self._sqlite_conn = sqlite3.connect(str(path))
+            self._sqlite_conn.row_factory = sqlite3.Row
+        return self._sqlite_conn
+
+    def set_mode(self, mode: str):
+        if mode not in ("auto", "pg", "sqlite"):
+            raise ValueError(f"Invalid mode: {mode}")
+        self.mode = mode
+        if mode == "pg" and self._pg_conn is None:
+            self._connect_pg()
+        if mode == "sqlite" and self._sqlite_conn is None:
+            self._connect_sqlite()
+
+    @property
+    def available(self) -> bool:
+        if self.mode == "sqlite":
+            return True
+        if self._pg_conn is None:
+            return False
+        try:
+            cur = self._pg_conn.cursor()
+            cur.execute("SELECT 1")
+            cur.close()
+            return True
+        except Exception:
+            return False
+
+    def _check_layer_write(self, layer: str, who: str):
+        allowed = LAYER_WRITERS.get(layer, frozenset())
+        who_prefix = who.split(":")[0] if ":" in who else who
+        if who_prefix not in allowed and who not in allowed:
+            raise WriteDenied(
+                f"Layer {layer} does not allow writes from '{who}'. "
+                f"Allowed: {sorted(allowed)}"
+            )
+
+    def insert(self, layer: str, type: str, content: str,
+               who: str = "system", source: str = "",
+               source_path: str = "", embedding: list = None,
+               created_at: str = None) -> dict:
+        if layer not in LAYER_AUTHORITY:
+            raise ValueError(f"Invalid layer: {layer}. Must be P0-P6")
+        self._check_layer_write(layer, who)
+
+        data = {
+            "who": who, "type": type, "layer": layer,
+            "authority": LAYER_AUTHORITY[layer],
+            "content": content[:100000],
+            "source": source, "source_path": source_path,
+        }
+        if created_at:
+            data["created_at"] = created_at
+
+        if self.mode != "sqlite" and self._pg_conn:
+            try:
+                return self._pg_insert(data, embedding)
+            except Exception as e:
+                logger.error("Pg insert failed, trying fallback: %s", e)
+                if self.mode == "pg":
+                    raise
+
+        return self._sqlite_insert(data)
+
+    def _pg_insert(self, data: dict, embedding: list = None) -> dict:
+        cur = self._pg_conn.cursor()
+        cols = list(data.keys())
+        placeholders = ["%s"] * len(cols)
+        values = [data[k] for k in cols]
+
+        if embedding is not None:
+            cols.append("embedding")
+            placeholders.append("%s")
+            values.append(np.array(embedding, dtype=np.float32))
+
+        cur.execute(
+            f"INSERT INTO entries ({', '.join(cols)}) "
+            f"VALUES ({', '.join(placeholders)}) "
+            f"RETURNING id, who, type, layer, authority, created_at",
+            values
+        )
+        row = cur.fetchone()
+        if not row:
+            raise DatabaseError("INSERT RETURNING returned no rows")
+        return {
+            "id": row[0], "who": row[1], "type": row[2],
+            "layer": row[3], "authority": row[4],
+            "created_at": row[5].isoformat() if row[5] else None,
+        }
+
+    def _sqlite_insert(self, data: dict) -> dict:
+        conn = self._connect_sqlite()
+        conn.execute(
+            "INSERT INTO memory_fts (fact, type) VALUES (?, ?)",
+            (data["content"], data["type"])
+        )
+        conn.commit()
+        return {"id": conn.execute("SELECT last_insert_rowid()").fetchone()[0], **data}
+
+    def search(self, query: str, layers: list = None,
+               limit: int = 20, who: str = None) -> list:
+        if self.mode != "sqlite" and self._pg_conn:
+            try:
+                return self._pg_search(query, layers, limit, who)
+            except Exception as e:
+                logger.error("Pg search failed, fallback: %s", e)
+                if self.mode == "pg":
+                    raise
+        return self._sqlite_search(query, limit)
+
+    def _pg_search(self, query: str, layers: list = None,
+                   limit: int = 20, who: str = None) -> list:
+        cur = self._pg_conn.cursor()
+        conditions = []
+        params = []
+
+        if layers:
+            placeholders = ", ".join(f"'{l}'" for l in layers)
+            conditions.append(f"layer IN ({placeholders})")
+        if who:
+            conditions.append("who = %s")
+            params.append(who)
+        if query:
+            conditions.append("tsv @@ plainto_tsquery('english', %s)")
+            params.append(query)
+
+        where = " AND ".join(conditions) if conditions else "TRUE"
+        sql = f"""
+            SELECT id, who, type, layer, authority,
+                   substring(content, 1, 200) as content_preview,
+                   created_at,
+                   ts_rank(tsv, plainto_tsquery('english', %s)) as rank
+            FROM entries
+            WHERE {where}
+            ORDER BY authority DESC, rank DESC, created_at DESC
+            LIMIT {limit}
+        """
+        all_params = [query] + params if query else params
+        cur.execute(sql, all_params if params else [query] if query else [])
+
+        results = []
+        for r in cur.fetchall():
+            results.append({
+                "id": r[0], "who": r[1], "type": r[2],
+                "layer": r[3], "authority": r[4],
+                "content": r[5], "created_at": r[6].isoformat() if r[6] else None,
+            })
+        return results
+
+    def _sqlite_search(self, query: str, limit: int = 20) -> list:
+        conn = self._connect_sqlite()
+        try:
+            rows = conn.execute(
+                "SELECT rowid, fact, type FROM memory_fts "
+                "WHERE memory_fts MATCH ? LIMIT ?",
+                (query, limit)
+            ).fetchall()
+            return [{"id": r[0], "content": r[1], "type": r[2], "layer": "P5"} for r in rows]
+        except sqlite3.OperationalError:
+            return []
+
+    def vector_search(self, embedding: list, layers: list = None,
+                      limit: int = 10) -> list:
+        if self.mode == "sqlite" or self._pg_conn is None:
+            return []
+        cur = self._pg_conn.cursor()
+        vec = np.array(embedding, dtype=np.float32)
+        layer_filter = ""
+        if layers:
+            placeholders = ", ".join(f"'{l}'" for l in layers)
+            layer_filter = f"AND layer IN ({placeholders})"
+
+        cur.execute(
+            f"""SELECT id, who, type, layer, authority,
+                       substring(content, 1, 200) as preview,
+                       created_at,
+                       1 - (embedding <=> %s) as similarity
+                FROM entries WHERE embedding IS NOT NULL {layer_filter}
+                ORDER BY embedding <=> %s LIMIT {limit}""",
+            (vec, vec)
+        )
+        results = []
+        for r in cur.fetchall():
+            results.append({
+                "id": r[0], "who": r[1], "type": r[2],
+                "layer": r[3], "authority": r[4],
+                "content": r[5], "created_at": r[6].isoformat() if r[6] else None,
+                "similarity": round(r[7], 4),
+            })
+        return results
+
+    def hybrid_search(self, query: str, embedding: list,
+                      layers: list = None, limit: int = 10) -> list:
+        if self.mode == "sqlite" or self._pg_conn is None:
+            return self._sqlite_search(query, limit)
+        cur = self._pg_conn.cursor()
+        vec = np.array(embedding, dtype=np.float32)
+        layer_filter = ""
+        if layers:
+            placeholders = ", ".join(f"'{l}'" for l in layers)
+            layer_filter = f"AND layer IN ({placeholders})"
+
+        cur.execute(
+            f"""SELECT id, who, type, layer, authority,
+                       substring(content, 1, 200) as preview, created_at,
+                       ts_rank(tsv, plainto_tsquery('english', %s)) as fts_score,
+                       1 - (embedding <=> %s) as vec_score,
+                       (ts_rank(tsv, plainto_tsquery('english', %s)) * 0.3 +
+                        (1 - (embedding <=> %s)) * 0.7) as combined
+                FROM entries
+                WHERE (tsv @@ plainto_tsquery('english', %s) OR embedding IS NOT NULL)
+                  {layer_filter}
+                ORDER BY combined DESC LIMIT {limit}""",
+            (query, vec, query, vec, query)
+        )
+        results = []
+        for r in cur.fetchall():
+            results.append({
+                "id": r[0], "who": r[1], "type": r[2],
+                "layer": r[3], "authority": r[4],
+                "content": r[5], "created_at": r[6].isoformat() if r[6] else None,
+                "combined_score": round(r[9], 4),
+            })
+        return results
+
+    def get_layer(self, layer: str, limit: int = 50) -> list:
+        return self.search("", layers=[layer], limit=limit)
+
+    def get_layer_count(self, layer: str = None) -> dict:
+        if self.mode == "sqlite" or self._pg_conn is None:
+            return {"sqlite": True}
+        cur = self._pg_conn.cursor()
+        if layer:
+            cur.execute("SELECT layer, COUNT(*) FROM entries WHERE layer = %s GROUP BY layer", (layer,))
+        else:
+            cur.execute("SELECT layer, COUNT(*) FROM entries GROUP BY layer ORDER BY layer")
+        return {r[0]: r[1] for r in cur.fetchall()}
+
+    def graph_query(self, entity_label: str, depth: int = 2) -> dict:
+        if self.mode == "sqlite" or self._pg_conn is None:
+            return {"nodes": [], "edges": []}
+        cur = self._pg_conn.cursor()
+        cur.execute("SELECT id, label, entity_type FROM entities WHERE label = %s", (entity_label,))
+        start = cur.fetchone()
+        if not start:
+            return {"nodes": [], "edges": []}
+
+        nodes = {start[0]: {"id": start[0], "label": start[1], "type": start[2]}}
+        edges = []
+        visited = {start[0]}
+        current = {start[0]}
+
+        for _ in range(depth):
+            if not current:
+                break
+            placeholders = ", ".join(str(i) for i in current)
+            cur.execute(
+                f"""SELECT r.id, r.source_id, r.target_id, r.rel_type,
+                           s.label as s_label, s.entity_type as s_type,
+                           t.label as t_label, t.entity_type as t_type
+                    FROM relations r
+                    JOIN entities s ON r.source_id = s.id
+                    JOIN entities t ON r.target_id = t.id
+                    WHERE r.source_id IN ({placeholders})
+                       OR r.target_id IN ({placeholders})"""
+            )
+            new_ids = set()
+            for r in cur.fetchall():
+                edges.append({"id": r[0], "source": r[1], "target": r[2], "type": r[3]})
+                if r[1] not in visited:
+                    nodes[r[1]] = {"id": r[1], "label": r[4], "type": r[5]}
+                    new_ids.add(r[1])
+                    visited.add(r[1])
+                if r[2] not in visited:
+                    nodes[r[2]] = {"id": r[2], "label": r[6], "type": r[7]}
+                    new_ids.add(r[2])
+                    visited.add(r[2])
+            current = new_ids
+        return {"nodes": list(nodes.values()), "edges": edges}
+
+    def health_check(self) -> dict:
+        result = {
+            "mode": self.mode,
+            "pg_available": self._pg_conn is not None and self.available,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        try:
+            result["counts"] = self.get_layer_count()
+        except Exception as e:
+            result["counts_error"] = str(e)
+        try:
+            test = self.insert(
+                layer="P6", type="health_check",
+                content=f"[HEALTH_CHECK] {time.time()}",
+                who="system:health"
+            )
+            result["write_test"] = "PASS"
+            if self._pg_conn:
+                cur = self._pg_conn.cursor()
+                cur.execute("DELETE FROM entries WHERE id = %s", (test["id"],))
+                cur.close()
+        except Exception as e:
+            result["write_test"] = f"FAIL: {e}"
+        return result
+
+    def close(self):
+        if self._pg_conn:
+            self._pg_conn.close()
+        if self._sqlite_conn:
+            self._sqlite_conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

p_layers-0.1.0/p_layer/core/memory.py

@@ -0,0 +1,114 @@
+"""Memory business logic — ranked recall, serendipity, TTL management."""
+
+import logging
+import random
+from datetime import datetime, timezone
+
+_SERENDIPITY_CHANCE = 0.05
+_DEFAULT_TTL = {"fact": 90, "decision": 180, "pattern": 30, "incident": 365}
+
+logger = logging.getLogger(__name__)
+
+
+def recall_ranked(db, query: str, limit: int = 10, layers: list = None,
+                  serendipity: bool = True) -> list:
+    """Recall with confidence-weighted ranking + serendipity.
+
+    Falls back to standard search when Pg is unavailable (SQLite mode).
+    """
+    has_pg = getattr(db, '_pg_conn', None) is not None
+
+    if not has_pg:
+        results = db.search(query, layers=layers or ["P5", "P6"], limit=limit)
+        return list(results) if results else []
+
+    cur = db._pg_conn.cursor()
+
+    where_parts = []
+    params = []
+    if layers:
+        placeholders = ", ".join("%s" for _ in layers)
+        where_parts.append(f"layer IN ({placeholders})")
+        params.extend(layers)
+
+    if query.strip():
+        where_parts.append("tsv @@ plainto_tsquery('english', %s)")
+        params.append(query)
+
+    where_sql = " AND ".join(where_parts) if where_parts else "TRUE"
+    ts_query = query.strip() or "."
+    rank_expr = "ts_rank(tsv, plainto_tsquery('english', %s))"
+
+    sql = f"""
+        SELECT id, content, type, layer, confidence, ttl_days,
+               access_count, last_accessed_at, version_id, created_at
+        FROM entries
+        WHERE {where_sql}
+          AND (superseded_by IS NULL)
+        ORDER BY
+            ({rank_expr} * (0.5 + confidence * 0.5) *
+             (1.0 + GREATEST(0.0, 1.0 - EXTRACT(EPOCH FROM (NOW() - created_at)) / 86400.0 /
+                    NULLIF(NULLIF(ttl_days, 0), 0)) * 0.3)) DESC
+        LIMIT %s
+    """
+    params.append(ts_query)
+    params.append(limit)
+
+    try:
+        cur.execute(sql, params)
+        rows = cur.fetchall()
+    except Exception as e:
+        logger.warning("Recall ranked query failed, falling back: %s", e)
+        rows = db.search(query, layers=layers or ["P5", "P6"], limit=limit)
+        rows = list(rows) if rows else []
+
+    seen_ids = []
+    results = []
+    for row in rows:
+        if isinstance(row, dict):
+            results.append(row)
+            if "id" in row:
+                seen_ids.append(row["id"])
+            continue
+        entry = {
+            "id": row[0], "content": row[1], "type": row[2],
+            "layer": row[3], "confidence": row[4], "ttl_days": row[5],
+            "access_count": row[6], "version_id": row[8],
+        }
+        seen_ids.append(row[0])
+        results.append(entry)
+
+    if seen_ids and has_pg:
+        try:
+            cur.execute(
+                "UPDATE entries SET access_count = access_count + 1, "
+                "last_accessed_at = NOW() WHERE id = ANY(%s)",
+                (seen_ids,)
+            )
+            db._pg_conn.commit()
+        except Exception:
+            db._pg_conn.rollback()
+
+    if serendipity and random.random() < _SERENDIPITY_CHANCE and seen_ids:
+        try:
+            cur.execute(
+                "SELECT id, content, type, layer, confidence, ttl_days, "
+                "access_count, version_id FROM entries "
+                "WHERE id != ALL(%s) AND (superseded_by IS NULL) "
+                "AND (access_count = 0 OR last_accessed_at IS NULL "
+                "OR last_accessed_at < NOW() - INTERVAL '60 days') "
+                "ORDER BY RANDOM() LIMIT 1",
+                (seen_ids,)
+            )
+            wild = cur.fetchone()
+            if wild:
+                results.append({
+                    "id": wild[0], "content": wild[1], "type": wild[2],
+                    "layer": wild[3], "confidence": wild[4], "ttl_days": wild[5],
+                    "access_count": wild[6], "version_id": wild[7],
+                    "_serendipity": True,
+                })
+        except Exception:
+            pass
+
+    return results

p_layers-0.1.0/p_layer/core/ontology.py

@@ -0,0 +1,49 @@
+"""Ontology type hierarchy and relation constraints.
+
+Reusable across both PostgreSQL and SQLite backends.
+"""
+
+TYPE_HIERARCHY = {
+    "artifact": None,
+    "doc": "artifact",
+    "code": "artifact",
+    "project": "artifact",
+    "agent": None,
+    "persona": "agent",
+    "tool": "agent",
+    "script": "agent",
+    "skill": "agent",
+    "decision": None,
+    "pattern": "decision",
+    "preference": "decision",
+    "event": None,
+    "incident": "event",
+    "session": "event",
+    "knowledge": None,
+    "concept": "knowledge",
+    "paper": "knowledge",
+    "reference": "knowledge",
+    "meta": None,
+    "category": "meta",
+    "_task": "meta",
+    "fact": "meta",
+}
+
+RELATION_CONSTRAINTS = {
+    "depends_on": (None, ("tool", "script", "skill")),
+    "fixed_by": (("incident",), ("pattern", "decision")),
+    "caused": (("decision", "pattern"), ("incident",)),
+    "led_to": (("decision", "pattern", "preference"), ("decision", "pattern", "preference")),
+    "implements": (("script",), ("pattern", "decision")),
+    "contradicts": (("decision", "pattern", "preference"), ("decision", "pattern", "preference")),
+    "cites": (("paper",), ("paper",)),
+    "references": None,
+    "relates_to": None,
+    "subtype_of": None,
+    "belongs_to": None,
+}
+
+ONTOLOGY = {
+    "type_hierarchy": TYPE_HIERARCHY,
+    "relation_constraints": RELATION_CONSTRAINTS,
+}

p_layers-0.1.0/p_layer/mcp/server.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""MCP Agent Memory Server — PgVector-backed with SQLite fallback.
+
+Tools:
+  knowledge_remember        — store a fact
+  knowledge_recall          — search with confidence ranking + serendipity
+  knowledge_forget          — supersede (soft-delete)
+  knowledge_update          — update by ID (bumps version)
+  knowledge_memory-stats    — stats
+  knowledge_snapshot-create — snapshot current entries
+  knowledge_snapshot-rollback — rollback to a snapshot
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from p_layer.core.db import KnowledgeDB
+from p_layer.core.memory import recall_ranked, _DEFAULT_TTL
+
+server = Server("knowledge-system")
+
+
+def get_db():
+    return KnowledgeDB()
+
+
+def _has_pg(db) -> bool:
+    return db._pg_conn is not None
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="knowledge_remember",
+            description="Store a fact, decision, pattern, or incident into persistent memory",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "fact": {"type": "string", "description": "The content to remember"},
+                    "type": {
+                        "type": "string",
+                        "enum": ["fact", "decision", "pattern", "incident"],
+                        "default": "fact",
+                    },
+                    "confidence": {
+                        "type": "number", "default": 1.0,
+                        "description": "Confidence score 0.0-1.0",
+                    },
+                    "ttl_days": {
+                        "type": "integer",
+                        "description": "Days before deprioritization (default: fact=90, decision=180, pattern=30, incident=365)",
+                    },
+                    "version_id": {
+                        "type": "string", "default": "latest",
+                        "description": "Version label for grouping",
+                    },
+                },
+                "required": ["fact"],
+            },
+        ),
+        Tool(
+            name="knowledge_recall",
+            description="Search persistent memory — ranked by relevance, confidence, and freshness",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search query"},
+                    "limit": {"type": "integer", "default": 10},
+                    "serendipity": {
+                        "type": "boolean", "default": True,
+                        "description": "Include a wildcard low-ranked entry",
+                    },
+                },
+                "required": ["query"],
+            },
+        ),
+        Tool(
+            name="knowledge_forget",
+            description="Supersede a memory entry (soft-delete)",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "integer", "description": "Entry ID to forget"},
+                    "reason": {"type": "string", "description": "Optional reason"},
+                },
+                "required": ["id"],
+            },
+        ),
+        Tool(
+            name="knowledge_memory-stats",
+            description="Show memory database statistics",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        Tool(
+            name="knowledge_update",
+            description="Update a memory entry — bumps version, old entry is superseded",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "integer", "description": "Entry ID"},
+                    "fact": {"type": "string", "description": "New content"},
+                    "type": {
+                        "type": "string",
+                        "enum": ["fact", "decision", "pattern", "incident"],
+                    },
+                    "confidence": {"type": "number", "description": "Updated confidence 0.0-1.0"},
+                },
+                "required": ["id"],
+            },
+        ),
+        Tool(
+            name="knowledge_snapshot-create",
+            description="Create a snapshot of current entries under a version label",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "version_id": {"type": "string", "description": "e.g. 'v1', 'v2.1'"},
+                    "label": {"type": "string", "description": "Human-readable description"},
+                },
+                "required": ["version_id"],
+            },
+        ),
+        Tool(
+            name="knowledge_snapshot-rollback",
+            description="Rollback to a snapshot — marks newer entries as superseded",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "version_id": {"type": "string", "description": "Snapshot version to rollback to"},
+                },
+                "required": ["version_id"],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    db = get_db()
+
+    if name == "knowledge_remember":
+        fact = arguments["fact"]
+        typ = arguments.get("type", "fact")
+        confidence = max(0.0, min(1.0, float(arguments.get("confidence", 1.0))))
+        ttl = arguments.get("ttl_days", _DEFAULT_TTL.get(typ, 90))
+        version_id = arguments.get("version_id", "latest")
+
+        result = db.insert(
+            layer="P6", type=typ, content=fact,
+            who="tool:knowledge-system",
+            source="knowledge_remember",
+        )
+
+        if _has_pg(db) and isinstance(result, dict) and result.get("id"):
+            try:
+                cur = db._pg_conn.cursor()
+                cur.execute(
+                    "UPDATE entries SET confidence = %s, ttl_days = %s, version_id = %s WHERE id = %s",
+                    (confidence, ttl, version_id, result["id"]),
+                )
+                db._pg_conn.commit()
+            except Exception:
+                db._pg_conn.rollback()
+
+        return [TextContent(type="text", text=str(result))]
+
+    elif name == "knowledge_recall":
+        query = arguments["query"]
+        limit = int(arguments.get("limit", 10))
+        serendipity = arguments.get("serendipity", True)
+
+        if not query.strip():
+            results = db.search("", layers=["P5", "P6"], limit=limit)
+        else:
+            results = recall_ranked(db, query, limit=limit, layers=["P5", "P6"], serendipity=serendipity)
+        return [TextContent(type="text", text=str(results))]
+
+    elif name == "knowledge_forget":
+        mem_id = int(arguments["id"])
+        reason = arguments.get("reason", "")
+
+        if _has_pg(db):
+            cur = db._pg_conn.cursor()
+            cur.execute(
+                "UPDATE entries SET superseded_by = id, confidence = GREATEST(confidence, 0.0), "
+                "updated_at = NOW() WHERE id = %s",
+                (mem_id,),
+            )
+            db._pg_conn.commit()
+            msg = {"superseded": cur.rowcount > 0, "id": mem_id}
+            if reason:
+                msg["reason"] = reason
+            return [TextContent(type="text", text=str(msg))]
+
+        cur = db._connect_sqlite().execute(
+            "DELETE FROM memory_fts WHERE rowid = ?", (mem_id,)
+        )
+        return [TextContent(type="text", text=str({"deleted": cur.rowcount > 0}))]
+
+    elif name == "knowledge_memory-stats":
+        counts = db.get_layer_count()
+        if _has_pg(db):
+            cur = db._pg_conn.cursor()
+            cur.execute("SELECT COUNT(*) FROM entries WHERE superseded_by IS NULL")
+            active = cur.fetchone()[0]
+            cur.execute("SELECT COUNT(*) FROM entries WHERE superseded_by IS NOT NULL")
+            superseded = cur.fetchone()[0]
+        else:
+            active = sum(counts.values())
+            superseded = 0
+        return [TextContent(type="text", text=str({
+            "total": sum(counts.values()) if isinstance(counts, dict) else 0,
+            "active": active,
+            "superseded": superseded,
+            "byLayer": counts,
+        }))]
+
+    elif name == "knowledge_update":
+        mem_id = int(arguments["id"])
+        fact = arguments.get("fact")
+        typ = arguments.get("type")
+        confidence = arguments.get("confidence")
+
+        if _has_pg(db):
+            cur = db._pg_conn.cursor()
+            if fact:
+                cur.execute(
+                    "UPDATE entries SET superseded_by = id, updated_at = NOW() WHERE id = %s",
+                    (mem_id,),
+                )
+                new_result = db.insert(
+                    layer="P6", type=typ or "fact", content=fact,
+                    who="tool:knowledge-system", source="knowledge_update",
+                )
+                if isinstance(new_result, dict) and new_result.get("id"):
+                    cur.execute(
+                        "UPDATE entries SET version_id = 'v2' WHERE id = %s",
+                        (new_result["id"],),
+                    )
+                db._pg_conn.commit()
+                return [TextContent(type="text", text=str({
+                    "updated": True, "superseded_id": mem_id,
+                    "new_id": new_result.get("id") if isinstance(new_result, dict) else None,
+                }))]
+
+            updates = []
+            params = []
+            if confidence is not None:
+                updates.append("confidence = %s")
+                params.append(max(0.0, min(1.0, float(confidence))))
+            if typ:
+                updates.append("type = %s")
+                params.append(typ)
+            if updates:
+                params.append(mem_id)
+                cur.execute(
+                    f"UPDATE entries SET {', '.join(updates)}, updated_at = NOW() WHERE id = %s",
+                    params,
+                )
+                db._pg_conn.commit()
+                return [TextContent(type="text", text=str({"updated": cur.rowcount > 0}))]
+
+        return [TextContent(type="text", text=str({"updated": False}))]
+
+    elif name == "knowledge_snapshot-create":
+        version_id = arguments["version_id"]
+        label = arguments.get("label", "")
+
+        if not _has_pg(db):
+            return [TextContent(type="text", text=str({"error": "PgVector required for snapshots"}))]
+
+        cur = db._pg_conn.cursor()
+        cur.execute("SELECT ARRAY_AGG(id) FROM entries WHERE superseded_by IS NULL")
+        entry_ids = cur.fetchone()[0] or []
+
+        cur.execute(
+            "INSERT INTO memory_snapshots (version_id, label, entry_ids) "
+            "VALUES (%s, %s, %s) "
+            "ON CONFLICT (version_id) DO UPDATE SET label = EXCLUDED.label, "
+            "entry_ids = EXCLUDED.entry_ids, created_at = NOW()",
+            (version_id, label, entry_ids),
+        )
+        db._pg_conn.commit()
+        return [TextContent(type="text", text=str({
+            "version_id": version_id, "entries_snapshot": len(entry_ids),
+            "created_at": datetime.now(timezone.utc).isoformat(),
+        }))]
+
+    elif name == "knowledge_snapshot-rollback":
+        version_id = arguments["version_id"]
+
+        if not _has_pg(db):
+            return [TextContent(type="text", text=str({"error": "PgVector required for snapshots"}))]
+
+        cur = db._pg_conn.cursor()
+        cur.execute(
+            "SELECT entry_ids, created_at FROM memory_snapshots WHERE version_id = %s",
+            (version_id,),
+        )
+        row = cur.fetchone()
+        if not row:
+            return [TextContent(type="text", text=str({"error": f"Snapshot '{version_id}' not found"}))]
+
+        snapshot_ids, snapshot_at = row
+        cur.execute(
+            "UPDATE entries SET superseded_by = id, updated_at = NOW() "
+            "WHERE id != ALL(%s) AND created_at > %s AND superseded_by IS NULL",
+            (snapshot_ids, snapshot_at),
+        )
+        affected = cur.rowcount
+        db._pg_conn.commit()
+
+        return [TextContent(type="text", text=str({
+            "version_id": version_id, "entries_rolled_forward": affected,
+            "snapshot_entries": len(snapshot_ids),
+            "note": "Entries superseded, not deleted. Recall ranking deprioritizes them.",
+        }))]
+
+    raise ValueError(f"Unknown tool: {name}")
+
+
+async def main():
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())

p_layers-0.1.0/p_layers.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: p-layers
+Version: 0.1.0
+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
+License-File: LICENSE
+Requires-Dist: mcp>=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"
+Dynamic: license-file

p_layers-0.1.0/p_layers.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+p_layer/__init__.py
+p_layer/core/__init__.py
+p_layer/core/db.py
+p_layer/core/memory.py
+p_layer/core/ontology.py
+p_layer/mcp/__init__.py
+p_layer/mcp/server.py
+p_layers.egg-info/PKG-INFO
+p_layers.egg-info/SOURCES.txt
+p_layers.egg-info/dependency_links.txt
+p_layers.egg-info/entry_points.txt
+p_layers.egg-info/requires.txt
+p_layers.egg-info/top_level.txt

p_layers-0.1.0/p_layers.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

p_layers-0.1.0/p_layers.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+p-layer-mcp = p_layer.mcp.server:main

p_layers-0.1.0/p_layers.egg-info/requires.txt

@@ -0,0 +1,6 @@
+mcp>=1.0
+
+[pg]
+psycopg2-binary>=2.9
+pgvector>=0.3
+numpy>=1.24

p_layers-0.1.0/p_layers.egg-info/top_level.txt

@@ -0,0 +1 @@
+p_layer

p_layers-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "p-layers"
+version = "0.1.0"
+description = "7 governance layers for AI agent memory — P0-P6 with KnowledgeDB, MCP server, and wiki-compile"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0",
+]
+[project.optional-dependencies]
+pg = [
+    "psycopg2-binary>=2.9",
+    "pgvector>=0.3",
+    "numpy>=1.24",
+]
+
+[project.urls]
+Home = "https://github.com/humanerd-drew/p-layer"
+
+[project.scripts]
+p-layer-mcp = "p_layer.mcp.server:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["p_layer*"]

p_layers-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+