feat: sync premium bootstrap template and docs

Author: RMANOV

README.md

@@ -8,7 +8,7 @@
 
 A production-quality SQLite-backed MCP Memory stack with WAL concurrent safety (10+ sessions), FTS5 BM25 search, session tracking, task management, bridge sync, collaboration workflows, and a native system tray task manager.
 
-Drop-in compatible with `@modelcontextprotocol/server-memory` for the core 9 knowledge-graph tools, with 41 additional tools split across companion FastMCP micro-servers for sessions, tasks, bridge sync, collaboration, entity linking, and intelligence workflows (50 tools total). Includes a PyQt6 desktop app for visual task management and standalone automation scripts.
+Drop-in compatible with `@modelcontextprotocol/server-memory` for the core 9 knowledge-graph tools, with 47 additional tools split across companion FastMCP micro-servers for sessions, tasks, bridge sync, collaboration, entity linking, and intelligence workflows (56 OSS tools total). Includes a PyQt6 desktop app for visual task management and standalone automation scripts.
 
 ## Why SQLite?
 
@@ -37,7 +37,7 @@ SQLite hits the sweet spot:
 - **Cross-project sharing** -- Optional `project` field scopes entities; omit it to share across all projects
 - **Cross-machine sync** -- Bridge tools push/pull shared entities between machines via a private git repo
 - **Premium runtime boundary** -- The OSS core can gate-load a separate private premium repo via signed entitlement checks, explicit owner approval, audit logging, and local revocation
-- **Drop-in compatible core** -- All 9 tools from `@modelcontextprotocol/server-memory` work identically in `sqlite_memory`, with 41 more tools available from companion servers
+- **Drop-in compatible core** -- All 9 tools from `@modelcontextprotocol/server-memory` work identically in `sqlite_memory`, with 47 more tools available from companion servers
 - **Zero required dependencies beyond stdlib** -- Only `fastmcp` is required for MCP protocol; `sqlite3` is Python stdlib. Optional `orjson`, `sqlite-vec`, and `sentence-transformers` add speed and semantic search
 - **Automatic FTS sync** -- Full-text index stays in sync with every write operation
 - **JSONL migration** -- Optionally import existing `memory.json` knowledge graphs on first run
@@ -83,6 +83,84 @@ The public runtime will only attempt to mount them when all of the following are
 
 Without a valid entitlement and local approval path, the premium runtime stays off and private extensions are not mounted.
 
+### Premium feature packs
+
+The premium layer is not meant to be a vague "enterprise edition". It is structured as a set of **gated operational packs** that sit on top of the OSS memory core.
+
+#### 1. ACL / RBAC control plane
+
+This pack is for teams that need more than "who has the database file".
+
+- define premium roles per global, project, client, or mailbox scope
+- assign those roles to users, teams, or agents
+- evaluate whether a principal may read, write, ingest, publish, or escalate within a given scope
+
+The point is not cosmetic permissions. The point is to stop one shared memory instance from becoming a flat trust domain once multiple people, clients, mailboxes, and AI agents are involved.
+
+#### 2. Governance / audit decision layer
+
+This pack records why a high-impact memory action was allowed, rejected, escalated, or published.
+
+- record governance decisions with rationale, evidence, and risk level
+- summarize the active governance surface for review
+- keep premium review activity in an auditable path instead of burying it in ad hoc notes
+
+This matters when the system starts influencing partner communication, escalation handling, or management-facing summaries.
+
+#### 3. Communication memory / multi-mailbox ingestion
+
+This pack turns the memory layer into a client-thread and operational follow-up surface.
+
+- register multiple mailboxes or shared inboxes
+- ingest thread/message metadata with client scope and participants
+- build follow-up queues based on the latest thread state
+- keep communication memory separated by mailbox and client boundary
+
+This is the premium line where the product stops being only "knowledge memory" and starts acting like governed operational memory.
+
+#### 4. Partner digest / management summary pipelines
+
+This is the premium summarization layer built on top of governance and communication memory.
+
+- partner-grade digests
+- management summaries
+- unresolved-risk and escalation views
+- high-signal briefings over selected scopes rather than global memory dumps
+
+These workflows are intentionally premium-only because they combine communication access, ranking, and decision framing in ways that should not run by default.
+
+#### 5. Advanced ranking / orchestration
+
+This pack is for cases where the public retrieval baseline is not enough.
+
+- premium reranking over client, partner, and mailbox context
+- queue prioritization and escalation ordering
+- multi-step orchestration for premium-only retrieval and digest pipelines
+
+The public repo exposes the runtime boundary for this. The proprietary heuristics and orchestration logic stay outside the OSS tree.
+
+#### 6. High-control deployment surfaces
+
+This is the control layer for customers that need stronger operational guarantees.
+
+- explicit entitlements
+- local revocation
+- owner approval for protected premium features
+- separate private runtime packaging
+- optional extra service boundaries for the most sensitive premium logic
+
+This is where the premium design stops depending on trust in the local machine and starts depending on gated execution, auditability, and runtime separation.
+
+### Current premium bootstrap scope
+
+The current private premium bootstrap is organized around three real pack families:
+
+- `acl_rbac`
+- `governance_audit`
+- `multi_mailbox_ingestion`
+
+That bootstrap is intentionally separate from the OSS repo. The public repo ships the airlock, contract, schema hooks, and template. The premium logic itself stays outside the OSS tree.
+
 See:
 
 - [`premium_contract.py`](premium_contract.py)
@@ -122,7 +200,7 @@ pip install -e .
 # Add the core drop-in server
 claude mcp add sqlite_memory python /path/to/server.py
 
-# Add companion servers for the full 50-tool stack
+# Add companion servers for the full 56-tool OSS stack
 claude mcp add sqlite_tasks python /path/to/task_server.py
 claude mcp add sqlite_session python /path/to/session_server.py
 claude mcp add sqlite_bridge python /path/to/bridge_server.py
@@ -162,7 +240,7 @@ Add these server/file pairs to your `~/.claude/settings.json` under `mcpServers`
 | `sqlite_collab` | `collab_server.py` | Collaborator and public-knowledge workflows |
 | `sqlite_entity` | `entity_server.py` | Task-entity linking and merge helpers |
 | `sqlite_intel` | `intel_server.py` | Context assessment and enrichment tools |
-| `sqlite_unified` | `unified_server.py` | Optional all-in-one server that mounts the full 50-tool stack |
+| `sqlite_unified` | `unified_server.py` | Optional all-in-one server that mounts the full 56-tool OSS stack |
 
 Each server should share the same environment values:
 
@@ -269,17 +347,17 @@ CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
 
 ## Tool Reference
 
-The 50 tools are grouped by MCP server:
+The 56 OSS tools are grouped by MCP server:
 
 | MCP server | Tool count | Tools |
 |---|---:|---|
 | `sqlite_memory` | 9 | `create_entities`, `add_observations`, `create_relations`, `delete_entities`, `delete_observations`, `delete_relations`, `read_graph`, `search_nodes`, `open_nodes` |
 | `sqlite_session` | 5 | `session_save`, `session_recall`, `search_by_project`, `knowledge_health`, `resume_context` |
-| `sqlite_tasks` | 6 | `create_task_or_note`, `update_task`, `query_tasks`, `task_digest`, `archive_done_tasks`, `bump_overdue_priority` |
-| `sqlite_bridge` | 6 | `bridge_push`, `bridge_pull`, `bridge_status`, `assign_task`, `review_shared_tasks`, `process_recurring_tasks` |
+| `sqlite_tasks` | 7 | `create_task_or_note`, `update_task`, `query_tasks`, `find_by_title`, `task_digest`, `archive_done_tasks`, `bump_overdue_priority` |
+| `sqlite_bridge` | 7 | `bridge_push`, `bridge_pull`, `bridge_status`, `bridge_doctor`, `assign_task`, `review_shared_tasks`, `process_recurring_tasks` |
 | `sqlite_collab` | 9 | `manage_collaborators`, `share_knowledge`, `review_shared_knowledge`, `request_publish`, `cancel_publish`, `search_public_knowledge`, `rate_public_knowledge`, `get_knowledge_ratings`, `update_verification` |
 | `sqlite_entity` | 7 | `link_task_entity`, `unlink_task_entity`, `get_task_links`, `get_entity_tasks`, `suggest_task_links`, `find_entity_overlaps`, `merge_entities` |
-| `sqlite_intel` | 8 | `assess_context`, `queue_clarification`, `record_human_answer`, `extract_candidate_claims`, `promote_candidate`, `build_context_pack`, `explain_impact`, `enrich_context` |
+| `sqlite_intel` | 12 | `assess_context`, `queue_clarification`, `record_human_answer`, `extract_candidate_claims`, `promote_candidate`, `build_context_pack`, `explain_impact`, `audit_memory`, `replay_memory`, `govern_fact`, `list_memory_issues`, `enrich_context` |
 
 ## Bridge Sync (Cross-Machine)
 

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "sqlite-memory-mcp"
-version = "3.4.0"
-description = "SQLite-backed MCP Memory Server with hybrid search (BM25 + semantic via sqlite-vec), Intelligence v2, causal event ledger, context state machine, knowledge tiers, WAL concurrent safety, cross-machine bridge sync, and 54 MCP tools"
+version = "3.5.0"
+description = "SQLite-backed MCP Memory Server with hybrid search (BM25 + semantic via sqlite-vec), Intelligence v2, causal event ledger, premium runtime boundary, context state machine, knowledge tiers, WAL concurrent safety, cross-machine bridge sync, and 56 OSS MCP tools"
 requires-python = ">=3.10"
 dependencies = ["fastmcp>=2.0.0"]
 license = {text = "MIT"}

templates/private_premium_repo/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/

templates/private_premium_repo/README.md

@@ -2,12 +2,16 @@
 
 Public-safe bootstrap template for a **separate private premium repo**.
 
+This template mirrors the resilient bootstrap layout of the real private
+premium runtime, but keeps the premium business logic replaced with safe
+placeholders.
+
 This template is intentionally safe to keep in the OSS repo:
 
 - no private keys
 - no customer entitlements
-- no premium business logic
-- no proprietary retrieval/ranking rules
+- no premium connector secrets
+- no proprietary ranking / governance logic
 
 ## Purpose
 
@@ -18,9 +22,25 @@ Use this template to start a private repository that implements:
 - private connector logic
 - premium governance / ACL / ingestion workflows
 
+## Template layout
+
+The template mirrors the private bootstrap structure:
+
+- `sqlite_memory_premium/app.py`
+- `sqlite_memory_premium/host_api.py`
+- `sqlite_memory_premium/runtime_state.py`
+- `sqlite_memory_premium/schema.py`
+- `sqlite_memory_premium/acl_governance.py`
+- `sqlite_memory_premium/communication_memory.py`
+- `sqlite_memory_premium/register.py`
+
+The placeholder tools in this template are there to preserve the contract and
+module boundaries, not to expose premium logic.
+
 ## Expected host
 
-This template is meant to run next to the public `sqlite-memory-mcp` repo and use:
+This template is meant to run next to the public `sqlite-memory-mcp` repo and
+use:
 
 - `premium_runtime.py`
 - `premium_contract.py`
@@ -29,10 +49,11 @@ This template is meant to run next to the public `sqlite-memory-mcp` repo and us
 
 1. Create a new **private** repo.
 2. Copy this template into that repo.
-3. Implement premium-only tools under `sqlite_memory_premium/`.
+3. Replace the placeholder tools in `sqlite_memory_premium/`.
 4. Point `SQLITE_MEMORY_PREMIUM_ENTRYPOINT` to the private module.
 5. Load through the gated public runtime only.
 
 ## Important boundary
 
-Do not move secrets, signatures, entitlement issuance, or real premium logic into the public repo.
+Do not move secrets, signatures, entitlement issuance, or real premium logic
+into the public repo.

templates/private_premium_repo/pyproject.toml

@@ -2,9 +2,13 @@
 name = "sqlite-memory-mcp-premium-template"
 version = "0.1.0"
 description = "Private premium repo template for sqlite-memory-mcp"
+readme = "README.md"
 requires-python = ">=3.10"
 dependencies = ["fastmcp>=2.0.0"]
 
 [build-system]
 requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["sqlite_memory_premium*"]

templates/private_premium_repo/sqlite_memory_premium/__init__.py

@@ -1 +1,4 @@
 """Private premium repo template package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

templates/private_premium_repo/sqlite_memory_premium/acl_governance.py

@@ -0,0 +1,139 @@
+"""Placeholder premium ACL and governance tools for the public template."""
+
+from __future__ import annotations
+
+import json
+
+from . import host_api
+from .app import premium_mcp
+from .runtime_state import denied_response, require_feature
+from .schema import ensure_private_schema
+
+
+def _template_response(feature_id: str, tool_name: str) -> str:
+    return json.dumps(
+        {
+            "status": "template_only",
+            "feature_id": feature_id,
+            "tool_name": tool_name,
+            "note": (
+                "Replace this placeholder with the real private premium implementation."
+            ),
+        },
+        ensure_ascii=False,
+        sort_keys=True,
+    )
+
+
+@premium_mcp.tool()
+def premium_acl_upsert_role(
+    role_name: str,
+    permissions_json: str,
+    description: str = "",
+    scope_kind: str = "global",
+    scope_ref: str = "",
+) -> str:
+    """Template placeholder for premium RBAC role definition."""
+    verdict = require_feature(
+        "acl_rbac",
+        tool_name="sqlite-premium-template.premium_acl_upsert_role",
+        payload={"role_name": role_name, "scope_kind": scope_kind},
+    )
+    if not verdict.get("allowed"):
+        return denied_response("acl_rbac", verdict)
+    with host_api.get_conn() as conn:
+        ensure_private_schema(conn)
+    return _template_response("acl_rbac", "premium_acl_upsert_role")
+
+
+@premium_mcp.tool()
+def premium_acl_assign_role(
+    principal_type: str,
+    principal_id: str,
+    role_name: str,
+    scope_kind: str = "global",
+    scope_ref: str = "",
+    granted_by: str = "system",
+    expires_at: str = "",
+) -> str:
+    """Template placeholder for premium RBAC role assignment."""
+    verdict = require_feature(
+        "acl_rbac",
+        tool_name="sqlite-premium-template.premium_acl_assign_role",
+        payload={"role_name": role_name, "principal_type": principal_type},
+    )
+    if not verdict.get("allowed"):
+        return denied_response("acl_rbac", verdict)
+    with host_api.get_conn() as conn:
+        ensure_private_schema(conn)
+    return _template_response("acl_rbac", "premium_acl_assign_role")
+
+
+@premium_mcp.tool()
+def premium_acl_check_access(
+    principal_type: str,
+    principal_id: str,
+    permission: str,
+    scope_kind: str = "global",
+    scope_ref: str = "",
+) -> str:
+    """Template placeholder for premium RBAC access evaluation."""
+    verdict = require_feature(
+        "acl_rbac",
+        tool_name="sqlite-premium-template.premium_acl_check_access",
+        payload={"principal_type": principal_type, "permission": permission},
+    )
+    if not verdict.get("allowed"):
+        return denied_response("acl_rbac", verdict)
+    with host_api.get_conn() as conn:
+        ensure_private_schema(conn)
+    return _template_response("acl_rbac", "premium_acl_check_access")
+
+
+@premium_mcp.tool()
+def premium_governance_record_decision(
+    title: str,
+    decision: str,
+    subject_kind: str,
+    subject_id: str = "",
+    rationale: str = "",
+    evidence_json: str = "[]",
+    risk_level: str = "medium",
+    scope_kind: str = "global",
+    scope_ref: str = "",
+    created_by: str = "system",
+) -> str:
+    """Template placeholder for premium governance decision recording."""
+    verdict = require_feature(
+        "governance_audit",
+        tool_name="sqlite-premium-template.premium_governance_record_decision",
+        payload={"title": title, "subject_kind": subject_kind},
+    )
+    if not verdict.get("allowed"):
+        return denied_response("governance_audit", verdict)
+    with host_api.get_conn() as conn:
+        ensure_private_schema(conn)
+    return _template_response(
+        "governance_audit",
+        "premium_governance_record_decision",
+    )
+
+
+@premium_mcp.tool()
+def premium_governance_audit_digest(
+    limit: int = 10,
+    risk_level: str = "",
+    scope_kind: str = "",
+    scope_ref: str = "",
+) -> str:
+    """Template placeholder for premium governance audit summaries."""
+    verdict = require_feature(
+        "governance_audit",
+        tool_name="sqlite-premium-template.premium_governance_audit_digest",
+        payload={"limit": limit, "risk_level": risk_level or None},
+    )
+    if not verdict.get("allowed"):
+        return denied_response("governance_audit", verdict)
+    with host_api.get_conn() as conn:
+        ensure_private_schema(conn)
+    return _template_response("governance_audit", "premium_governance_audit_digest")

templates/private_premium_repo/sqlite_memory_premium/app.py

@@ -0,0 +1,13 @@
+"""Shared FastMCP app for template premium tools."""
+
+from __future__ import annotations
+
+from fastmcp import FastMCP
+
+premium_mcp = FastMCP(
+    "sqlite-memory-premium-template",
+    instructions=(
+        "Template private premium MCP runtime for sqlite-memory-mcp. "
+        "Replace the placeholder tools with real premium-only capabilities."
+    ),
+)