memory-arbiter-mcp 0.1.0__py3-none-any.whl

memory_arbiter/__init__.py

@@ -0,0 +1,3 @@
+"""Memory Arbiter MCP package."""
+
+__version__ = "0.1.0"

memory_arbiter/arbitration.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from .models import ProtectionLevel, SourceType
+
+
+SOURCE_RANK = {
+    SourceType.USER_CONFIRMED.value: 100,
+    SourceType.DOCUMENT_EXTRACTED.value: 70,
+    SourceType.AGENT_GENERATED.value: 45,
+    SourceType.PENDING.value: 20,
+    SourceType.UNKNOWN.value: 10,
+}
+
+
+def compare_memories(left: dict[str, Any], right: dict[str, Any]) -> dict[str, Any]:
+    reasons: list[str] = []
+    left_protected = is_user_protected(left)
+    right_protected = is_user_protected(right)
+    if left_protected and not right_protected:
+        return decision(left, right, left, "left", ["left is user_confirmed or locked; automatic overwrite is forbidden"])
+    if right_protected and not left_protected:
+        return decision(left, right, right, "right", ["right is user_confirmed or locked; automatic overwrite is forbidden"])
+    if left_protected and right_protected:
+        return decision(left, right, None, "manual_review", ["both records are user protected; manual review required"])
+
+    left_event = parse_time(left.get("event_time"))
+    right_event = parse_time(right.get("event_time"))
+    if left_event != right_event:
+        winner = left if left_event > right_event else right
+        side = "left" if winner is left else "right"
+        reasons.append(f"{side} has newer event_time; fact occurrence time has priority")
+        return decision(left, right, winner, side, reasons)
+
+    left_source = SOURCE_RANK.get(left.get("source_type"), 0)
+    right_source = SOURCE_RANK.get(right.get("source_type"), 0)
+    if left_source != right_source:
+        winner = left if left_source > right_source else right
+        side = "left" if winner is left else "right"
+        reasons.append(f"{side} has stronger source_type")
+        return decision(left, right, winner, side, reasons)
+
+    left_conf = float(left.get("confidence") or 0)
+    right_conf = float(right.get("confidence") or 0)
+    if left_conf != right_conf:
+        winner = left if left_conf > right_conf else right
+        side = "left" if winner is left else "right"
+        reasons.append(f"{side} has higher confidence")
+        return decision(left, right, winner, side, reasons)
+
+    left_ingest = parse_time(left.get("ingest_time"))
+    right_ingest = parse_time(right.get("ingest_time"))
+    if left_ingest != right_ingest:
+        winner = left if left_ingest > right_ingest else right
+        side = "left" if winner is left else "right"
+        reasons.append(f"{side} has newer ingest_time after equal event_time/source/confidence")
+        return decision(left, right, winner, side, reasons)
+
+    return decision(left, right, None, "tie", ["records are equivalent under configured arbitration rules"])
+
+
+def is_user_protected(record: dict[str, Any]) -> bool:
+    return record.get("source_type") == SourceType.USER_CONFIRMED.value or record.get("protection_level") in {
+        ProtectionLevel.LOCKED.value,
+        ProtectionLevel.PROTECTED.value,
+    }
+
+
+def parse_time(value: Any) -> datetime:
+    if not value:
+        return datetime.min.replace(tzinfo=timezone.utc)
+    try:
+        parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        return parsed.astimezone(timezone.utc)
+    except ValueError:
+        return datetime.min.replace(tzinfo=timezone.utc)
+
+
+def decision(left: dict[str, Any], right: dict[str, Any], winner: Optional[dict[str, Any]], side: str, reasons: list[str]) -> dict[str, Any]:
+    loser = None
+    if winner:
+        loser = right if winner.get("id") == left.get("id") else left
+    return {
+        "winner_side": side,
+        "winner_id": winner.get("id") if winner else None,
+        "loser_id": loser.get("id") if loser else None,
+        "manual_review": side in {"manual_review", "tie"},
+        "reasons": reasons,
+        "rule_order": [
+            "user_confirmed/locked protection",
+            "event_time",
+            "source_type",
+            "confidence",
+            "ingest_time",
+        ],
+    }

memory_arbiter/config.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+
+@dataclass
+class AgentPolicy:
+    # Per-client overrides. Any client *not* listed here defaults to enabled.
+    client_defaults: dict[str, bool] = field(default_factory=dict)
+    default_enabled: bool = True
+    allow_agents: list[str] = field(default_factory=list)
+    deny_agents: list[str] = field(default_factory=list)
+
+    def enabled_for(self, client: str, agent_id: str) -> bool:
+        if agent_id in self.deny_agents:
+            return False
+        if agent_id in self.allow_agents:
+            return True
+        normalized = (client or "").lower()
+        if normalized in self.client_defaults:
+            return self.client_defaults[normalized]
+        # Default-allow: any unrecognised client is enabled.
+        return True
+
+
+@dataclass
+class Settings:
+    db_path: Path
+    backup_jsonl: Path
+    policy_path: Optional[Path] = None
+    client: str = "codex"
+    agent_id: str = "default"
+    workspace: str = "default"
+    enable_sqlite_vec: bool = True
+    policy: AgentPolicy = field(default_factory=AgentPolicy)
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        cwd = Path.cwd()
+        policy_raw = os.getenv("MEMORY_ARBITER_POLICY")
+        settings = cls(
+            db_path=Path(os.getenv("MEMORY_ARBITER_DB_PATH", cwd / "memory_arbiter.sqlite3")).expanduser(),
+            backup_jsonl=Path(os.getenv("MEMORY_ARBITER_BACKUP_JSONL", cwd / "memory_arbiter.backup.jsonl")).expanduser(),
+            policy_path=Path(policy_raw).expanduser() if policy_raw else None,
+            client=os.getenv("MEMORY_ARBITER_CLIENT", "codex"),
+            agent_id=os.getenv("MEMORY_ARBITER_AGENT_ID", "default"),
+            workspace=os.getenv("MEMORY_ARBITER_WORKSPACE", "default"),
+            enable_sqlite_vec=os.getenv("MEMORY_ARBITER_ENABLE_SQLITE_VEC", "true").lower() not in {"0", "false", "no"},
+        )
+        settings.policy = load_policy(settings.policy_path)
+        return settings
+
+    def defaults(self) -> dict[str, str]:
+        return {"agent_id": self.agent_id, "workspace": self.workspace}
+
+
+def load_policy(path: Optional[Path]) -> AgentPolicy:
+    if not path or not path.exists():
+        return AgentPolicy()
+    with path.open("r", encoding="utf-8") as fh:
+        raw: dict[str, Any] = json.load(fh)
+    return AgentPolicy(
+        client_defaults=dict(raw.get("client_defaults") or AgentPolicy().client_defaults),
+        default_enabled=bool(raw.get("default_enabled", True)),
+        allow_agents=list(raw.get("allow_agents") or []),
+        deny_agents=list(raw.get("deny_agents") or []),
+    )

memory_arbiter/db.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any, Optional, Tuple
+
+from .config import Settings
+from .degrade import DegradeState
+from .models import MemoryRecord, utc_now_iso
+
+
+class MemoryDB:
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self.state = DegradeState()
+        self.conn: Optional[sqlite3.Connection] = None
+        self._connect()
+
+    def _connect(self) -> None:
+        self.settings.db_path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            self.conn = sqlite3.connect(str(self.settings.db_path))
+            self.conn.row_factory = sqlite3.Row
+            self.conn.execute("PRAGMA journal_mode=WAL")
+            self.conn.execute("PRAGMA foreign_keys=ON")
+            self._init_schema()
+            self._probe_features()
+        except sqlite3.Error as exc:
+            self.conn = None
+            self.state.sqlite_writable = False
+            self.state.mode = "jsonl_backup"
+            self.state.jsonl_backup_active = True
+            self.state.warn(f"SQLite unavailable or not writable: {exc}. Using JSONL append-only backup when possible.")
+
+    def _init_schema(self) -> None:
+        assert self.conn is not None
+        self.conn.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS memories (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              content TEXT NOT NULL,
+              agent_id TEXT NOT NULL,
+              workspace TEXT NOT NULL,
+              tags TEXT NOT NULL DEFAULT '[]',
+              source_type TEXT NOT NULL,
+              source_ref TEXT,
+              event_time TEXT NOT NULL,
+              ingest_time TEXT NOT NULL,
+              confidence REAL NOT NULL DEFAULT 0.5,
+              protection_level TEXT NOT NULL DEFAULT 'normal',
+              status TEXT NOT NULL DEFAULT 'active',
+              subject TEXT,
+              metadata TEXT NOT NULL DEFAULT '{}',
+              created_at TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS conflicts (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              left_id INTEGER NOT NULL,
+              right_id INTEGER NOT NULL,
+              subject TEXT,
+              status TEXT NOT NULL DEFAULT 'open',
+              reason TEXT NOT NULL,
+              winner_id INTEGER,
+              created_at TEXT NOT NULL,
+              resolved_at TEXT,
+              FOREIGN KEY(left_id) REFERENCES memories(id),
+              FOREIGN KEY(right_id) REFERENCES memories(id)
+            );
+            CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(workspace, agent_id, status);
+            CREATE INDEX IF NOT EXISTS idx_memories_subject ON memories(workspace, subject);
+            CREATE INDEX IF NOT EXISTS idx_memories_event ON memories(event_time, ingest_time);
+            """
+        )
+        self.conn.commit()
+
+    def _probe_features(self) -> None:
+        assert self.conn is not None
+        if self.settings.enable_sqlite_vec:
+            try:
+                import sqlite_vec  # type: ignore
+
+                self.conn.enable_load_extension(True)
+                sqlite_vec.load(self.conn)
+                self.state.sqlite_vec_available = True
+                self.state.mode = "sqlite_vec"
+            except Exception as exc:  # pragma: no cover - depends on local optional package
+                self.state.warn(f"sqlite-vec unavailable: {exc}. Semantic recall disabled; falling back to FTS5 or keyword search.")
+        else:
+            self.state.warn("sqlite-vec disabled by configuration. Semantic recall disabled.")
+
+        try:
+            self.conn.execute(
+                "CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(content, tags, subject, content='memories', content_rowid='id')"
+            )
+            self._rebuild_fts()
+            self.state.fts5_available = True
+            if not self.state.sqlite_vec_available:
+                self.state.mode = "fts5"
+        except sqlite3.Error as exc:
+            self.state.warn(f"SQLite FTS5 unavailable: {exc}. Falling back to LIKE/keyword search.")
+            if not self.state.sqlite_vec_available:
+                self.state.mode = "like"
+
+        try:
+            self.conn.execute("CREATE TABLE IF NOT EXISTS write_probe (id INTEGER)")
+            self.conn.execute("INSERT INTO write_probe(id) VALUES (1)")
+            self.conn.execute("DELETE FROM write_probe")
+            self.conn.commit()
+        except sqlite3.Error as exc:
+            self.state.sqlite_writable = False
+            self.state.mode = "jsonl_backup"
+            self.state.jsonl_backup_active = True
+            self.state.warn(f"SQLite opened read-only or write probe failed: {exc}. Writes will use JSONL backup when possible.")
+
+    def _rebuild_fts(self) -> None:
+        assert self.conn is not None
+        try:
+            self.conn.execute("INSERT INTO memories_fts(memories_fts) VALUES ('rebuild')")
+            self.conn.commit()
+        except sqlite3.Error:
+            self.conn.rollback()
+
+    def insert_memory(self, record: MemoryRecord) -> Tuple[Optional[int], list[str]]:
+        warnings: list[str] = []
+        if not record.content:
+            raise ValueError("content is required")
+        if self.conn is None or not self.state.sqlite_writable:
+            self._append_backup(record)
+            warnings.append("SQLite write unavailable; wrote append-only JSONL backup.")
+            return None, warnings
+        cur = self.conn.execute(
+            """
+            INSERT INTO memories
+            (content, agent_id, workspace, tags, source_type, source_ref, event_time, ingest_time,
+             confidence, protection_level, status, subject, metadata, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                record.content,
+                record.agent_id,
+                record.workspace,
+                json.dumps(record.tags, ensure_ascii=False),
+                record.source_type,
+                record.source_ref,
+                record.event_time,
+                record.ingest_time,
+                record.confidence,
+                record.protection_level,
+                record.status,
+                record.subject,
+                json.dumps(record.metadata, ensure_ascii=False),
+                utc_now_iso(),
+            ),
+        )
+        memory_id = int(cur.lastrowid)
+        if self.state.fts5_available:
+            self.conn.execute(
+                "INSERT INTO memories_fts(rowid, content, tags, subject) VALUES (?, ?, ?, ?)",
+                (memory_id, record.content, " ".join(record.tags), record.subject or ""),
+            )
+        self.conn.commit()
+        return memory_id, warnings
+
+    def _append_backup(self, record: MemoryRecord) -> None:
+        self.settings.backup_jsonl.parent.mkdir(parents=True, exist_ok=True)
+        payload = record.__dict__.copy()
+        payload["backup_written_at"] = utc_now_iso()
+        with self.settings.backup_jsonl.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(payload, ensure_ascii=False) + "\n")
+        self.state.jsonl_backup_active = True
+
+    def get_memory(self, memory_id: int) -> Optional[dict[str, Any]]:
+        if self.conn is None:
+            return None
+        row = self.conn.execute("SELECT * FROM memories WHERE id = ?", (memory_id,)).fetchone()
+        return row_to_dict(row) if row else None
+
+    def update_memory(self, memory_id: int, updates: dict[str, Any]) -> bool:
+        if self.conn is None or not self.state.sqlite_writable:
+            return False
+        allowed = {"source_type", "confidence", "protection_level", "status", "metadata"}
+        pairs = [(key, value) for key, value in updates.items() if key in allowed]
+        if not pairs:
+            return True
+        sql = ", ".join(f"{key} = ?" for key, _ in pairs)
+        values = [json.dumps(v, ensure_ascii=False) if isinstance(v, (dict, list)) else v for _, v in pairs]
+        values.append(memory_id)
+        self.conn.execute(f"UPDATE memories SET {sql} WHERE id = ?", values)
+        self.conn.commit()
+        return True
+
+    def list_memories(self, workspace: Optional[str] = None, subject: Optional[str] = None, limit: int = 50) -> list[dict[str, Any]]:
+        if self.conn is None:
+            return []
+        clauses = ["status != 'deleted'"]
+        params: list[Any] = []
+        if workspace:
+            clauses.append("workspace = ?")
+            params.append(workspace)
+        if subject:
+            clauses.append("subject = ?")
+            params.append(subject)
+        params.append(limit)
+        rows = self.conn.execute(
+            f"SELECT * FROM memories WHERE {' AND '.join(clauses)} ORDER BY event_time DESC, ingest_time DESC LIMIT ?",
+            params,
+        ).fetchall()
+        return [row_to_dict(row) for row in rows]
+
+    def record_conflict(self, left_id: int, right_id: int, subject: Optional[str], reason: str, winner_id: Optional[int]) -> Optional[int]:
+        if self.conn is None or not self.state.sqlite_writable:
+            return None
+        cur = self.conn.execute(
+            """
+            INSERT INTO conflicts(left_id, right_id, subject, reason, winner_id, created_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+            """,
+            (left_id, right_id, subject, reason, winner_id, utc_now_iso()),
+        )
+        self.conn.commit()
+        return int(cur.lastrowid)
+
+    def list_conflicts(self, status: str = "open", limit: int = 50) -> list[dict[str, Any]]:
+        if self.conn is None:
+            return []
+        rows = self.conn.execute(
+            "SELECT * FROM conflicts WHERE status = ? ORDER BY created_at DESC LIMIT ?",
+            (status, limit),
+        ).fetchall()
+        return [row_to_dict(row) for row in rows]
+
+
+def row_to_dict(row: sqlite3.Row) -> dict[str, Any]:
+    data = dict(row)
+    for key in ("tags", "metadata"):
+        if key in data and isinstance(data[key], str):
+            try:
+                data[key] = json.loads(data[key])
+            except json.JSONDecodeError:
+                pass
+    return data

memory_arbiter/degrade.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class DegradeState:
+    mode: str = "sqlite"
+    warnings: list[str] = field(default_factory=list)
+    sqlite_vec_available: bool = False
+    fts5_available: bool = False
+    sqlite_writable: bool = True
+    jsonl_backup_active: bool = False
+
+    @property
+    def degraded(self) -> bool:
+        return bool(self.warnings) or self.mode != "sqlite_vec"
+
+    def warn(self, message: str) -> None:
+        if message not in self.warnings:
+            self.warnings.append(message)
+
+    def response(self, data: Any, ok: bool = True, extra_warnings: Optional[list[str]] = None) -> dict[str, Any]:
+        warnings = list(self.warnings)
+        for warning in extra_warnings or []:
+            if warning not in warnings:
+                warnings.append(warning)
+        return {
+            "ok": ok,
+            "mode": self.mode,
+            "warnings": warnings,
+            "degraded": bool(warnings) or self.mode != "sqlite_vec",
+            "data": data,
+        }

memory_arbiter/models.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Optional
+
+
+class SourceType(str, Enum):
+    USER_CONFIRMED = "user_confirmed"
+    DOCUMENT_EXTRACTED = "document_extracted"
+    AGENT_GENERATED = "agent_generated"
+    UNKNOWN = "unknown"
+    PENDING = "pending"
+
+
+class ProtectionLevel(str, Enum):
+    NORMAL = "normal"
+    PROTECTED = "protected"
+    LOCKED = "locked"
+
+
+class MemoryStatus(str, Enum):
+    ACTIVE = "active"
+    SUPERSEDED = "superseded"
+    CONFLICTED = "conflicted"
+    PENDING = "pending"
+    DELETED = "deleted"
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def normalize_iso(value: Optional[str]) -> str:
+    if not value:
+        return utc_now_iso()
+    try:
+        normalized = value.replace("Z", "+00:00")
+        parsed = datetime.fromisoformat(normalized)
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        return parsed.astimezone(timezone.utc).replace(microsecond=0).isoformat()
+    except ValueError:
+        return value
+
+
+@dataclass
+class MemoryRecord:
+    content: str
+    agent_id: str
+    workspace: str
+    tags: list[str] = field(default_factory=list)
+    source_type: str = SourceType.UNKNOWN.value
+    source_ref: Optional[str] = None
+    event_time: str = field(default_factory=utc_now_iso)
+    ingest_time: str = field(default_factory=utc_now_iso)
+    confidence: float = 0.5
+    protection_level: str = ProtectionLevel.NORMAL.value
+    status: str = MemoryStatus.ACTIVE.value
+    subject: Optional[str] = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    id: Optional[int] = None
+
+    @classmethod
+    def from_input(cls, payload: dict[str, Any], defaults: dict[str, str]) -> "MemoryRecord":
+        source_type = payload.get("source_type") or SourceType.UNKNOWN.value
+        protection = payload.get("protection_level") or ProtectionLevel.NORMAL.value
+        status = payload.get("status") or MemoryStatus.ACTIVE.value
+        if source_type == SourceType.USER_CONFIRMED.value:
+            protection = ProtectionLevel.LOCKED.value
+            status = MemoryStatus.ACTIVE.value
+        return cls(
+            content=str(payload["content"]).strip(),
+            agent_id=str(payload.get("agent_id") or defaults.get("agent_id") or "default"),
+            workspace=str(payload.get("workspace") or defaults.get("workspace") or "default"),
+            tags=list(payload.get("tags") or []),
+            source_type=str(source_type),
+            source_ref=payload.get("source_ref"),
+            event_time=normalize_iso(payload.get("event_time")),
+            ingest_time=normalize_iso(payload.get("ingest_time")),
+            confidence=float(payload.get("confidence", 0.5)),
+            protection_level=str(protection),
+            status=str(status),
+            subject=payload.get("subject"),
+            metadata=dict(payload.get("metadata") or {}),
+        )

memory_arbiter/search.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple
+
+from .db import MemoryDB, row_to_dict
+
+
+def search_memories(db: MemoryDB, query: str, workspace: Optional[str] = None, tags: Optional[list[str]] = None, limit: int = 10) -> Tuple[list[dict[str, Any]], list[str]]:
+    warnings: list[str] = []
+    if db.conn is None:
+        return [], ["SQLite unavailable; search cannot read JSONL backup in MVP."]
+    limit = max(1, min(int(limit), 100))
+    query = (query or "").strip()
+    rows = []
+    if db.state.fts5_available and query:
+        sql = """
+            SELECT m.*, bm25(memories_fts) AS score
+            FROM memories_fts
+            JOIN memories m ON memories_fts.rowid = m.id
+            WHERE memories_fts MATCH ? AND m.status != 'deleted'
+        """
+        params: list[Any] = [query]
+        if workspace:
+            sql += " AND m.workspace = ?"
+            params.append(workspace)
+        sql += " ORDER BY score LIMIT ?"
+        params.append(limit)
+        try:
+            rows = db.conn.execute(sql, params).fetchall()
+        except Exception as exc:
+            warnings.append(f"FTS5 query failed: {exc}. Falling back to LIKE search.")
+            rows = []
+    if not rows:
+        like = f"%{query}%"
+        clauses = ["status != 'deleted'"]
+        params = []
+        if query:
+            clauses.append("(content LIKE ? OR subject LIKE ? OR tags LIKE ?)")
+            params.extend([like, like, like])
+        if workspace:
+            clauses.append("workspace = ?")
+            params.append(workspace)
+        for tag in tags or []:
+            clauses.append("tags LIKE ?")
+            params.append(f"%{tag}%")
+        params.append(limit)
+        rows = db.conn.execute(
+            f"SELECT *, 0 AS score FROM memories WHERE {' AND '.join(clauses)} ORDER BY event_time DESC, ingest_time DESC LIMIT ?",
+            params,
+        ).fetchall()
+        if query and not db.state.fts5_available:
+            warnings.append("Using LIKE/keyword search because sqlite-vec and FTS5 are unavailable.")
+    return [row_to_dict(row) for row in rows], warnings

memory_arbiter/server.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import sys
+from typing import Any, Optional
+
+from .config import Settings
+from .tools import MemoryTools
+
+
+def build_server() -> Any:
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except Exception as exc:
+        raise RuntimeError(
+            "MCP Python SDK is not installed. Install with `pip install -r requirements.txt` "
+            "or `pip install mcp`, then run `memory-arbiter-mcp` again."
+        ) from exc
+
+    app = FastMCP("memory-arbiter-mcp")
+    tools = MemoryTools(Settings.from_env())
+
+    @app.tool()
+    def memory_write(
+        content: str,
+        agent_id: Optional[str] = None,
+        workspace: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        source_type: str = "unknown",
+        source_ref: Optional[str] = None,
+        event_time: Optional[str] = None,
+        ingest_time: Optional[str] = None,
+        confidence: float = 0.5,
+        protection_level: str = "normal",
+        status: str = "active",
+        subject: Optional[str] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """写入一条结构化记忆到跨工具共享记忆库。必填 content（正文），建议填 subject（标题）、tags（标签）、source_type（来源类型：agent_generated/user_confirmed/document_extracted）。"""
+        return tools.memory_write(
+            content=content,
+            agent_id=agent_id,
+            workspace=workspace,
+            tags=tags or [],
+            source_type=source_type,
+            source_ref=source_ref,
+            event_time=event_time,
+            ingest_time=ingest_time,
+            confidence=confidence,
+            protection_level=protection_level,
+            status=status,
+            subject=subject,
+            metadata=metadata or {},
+        )
+
+    @app.tool()
+    def memory_search(query: str = "", workspace: Optional[str] = None, tags: Optional[list[str]] = None, limit: int = 10) -> dict[str, Any]:
+        """按关键词搜索跨工具共享记忆库中的已有记忆。开始新任务前先搜一下，避免重复记录。"""
+        return tools.memory_search(query=query, workspace=workspace, tags=tags or [], limit=limit)
+
+    @app.tool()
+    def memory_compare(left_id: int, right_id: int) -> dict[str, Any]:
+        """比较两条记忆是否冲突，返回可解释的比较理由，不落冲突记录。"""
+        return tools.memory_compare(left_id=left_id, right_id=right_id)
+
+    @app.tool()
+    def memory_arbitrate(left_id: int, right_id: int, mark_conflict: bool = True, apply: bool = False) -> dict[str, Any]:
+        """仲裁两条冲突记忆的胜者与败者。mark_conflict=true 记录冲突，apply=true 自动将非保护败方标记为 superseded。"""
+        return tools.memory_arbitrate(left_id=left_id, right_id=right_id, mark_conflict=mark_conflict, apply=apply)
+
+    @app.tool()
+    def memory_list_conflicts(status: str = "open", limit: int = 50) -> dict[str, Any]:
+        """列出记忆冲突记录，默认只看 open 状态。"""
+        return tools.memory_list_conflicts(status=status, limit=limit)
+
+    @app.tool()
+    def memory_confirm(memory_id: int, source_ref: Optional[str] = None, confidence: float = 1.0) -> dict[str, Any]:
+        """将一条记忆标记为用户确认，提升为 user_confirmed + locked 保护级别，禁止自动覆盖。"""
+        return tools.memory_confirm(memory_id=memory_id, source_ref=source_ref, confidence=confidence)
+
+    @app.tool()
+    def memory_status() -> dict[str, Any]:
+        """查看 memory-arbiter 运行状态：数据库路径、降级模式、客户端标识、策略配置。"""
+        return tools.memory_status()
+
+    return app
+
+
+def main() -> None:
+    try:
+        build_server().run()
+    except RuntimeError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(2)
+
+
+if __name__ == "__main__":
+    main()

memory_arbiter/tools.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple
+
+from .arbitration import compare_memories
+from .config import Settings
+from .db import MemoryDB
+from .models import MemoryRecord, ProtectionLevel, SourceType
+from .search import search_memories
+
+
+class MemoryTools:
+    def __init__(self, settings: Optional[Settings] = None, db: Optional[MemoryDB] = None):
+        self.settings = settings or Settings.from_env()
+        self.db = db or MemoryDB(self.settings)
+
+    def _allowed(self, agent_id: Optional[str] = None, client: Optional[str] = None) -> Tuple[bool, list[str]]:
+        actual_agent = agent_id or self.settings.agent_id
+        actual_client = client or self.settings.client
+        if self.settings.policy.enabled_for(actual_client, actual_agent):
+            return True, []
+        return False, [f"Memory arbiter disabled by policy for client={actual_client}, agent_id={actual_agent}."]
+
+    def memory_write(self, **payload: Any) -> dict[str, Any]:
+        allowed, warnings = self._allowed(payload.get("agent_id"), payload.get("client"))
+        if not allowed:
+            return self.db.state.response({"written": False}, ok=False, extra_warnings=warnings)
+        try:
+            record = MemoryRecord.from_input(payload, self.settings.defaults())
+            memory_id, write_warnings = self.db.insert_memory(record)
+            data = {"id": memory_id, "backup_only": memory_id is None, "record": {**record.__dict__, "id": memory_id}}
+            return self.db.state.response(data, extra_warnings=warnings + write_warnings)
+        except Exception as exc:
+            return self.db.state.response({"error": str(exc)}, ok=False, extra_warnings=warnings)
+
+    def memory_search(self, query: str = "", workspace: Optional[str] = None, tags: Optional[list[str]] = None, limit: int = 10, **_: Any) -> dict[str, Any]:
+        results, warnings = search_memories(self.db, query, workspace or self.settings.workspace, tags, limit)
+        return self.db.state.response({"results": results, "count": len(results)}, extra_warnings=warnings)
+
+    def memory_compare(self, left_id: Optional[int] = None, right_id: Optional[int] = None, left: Optional[dict[str, Any]] = None, right: Optional[dict[str, Any]] = None, **_: Any) -> dict[str, Any]:
+        left_record = left or (self.db.get_memory(int(left_id)) if left_id is not None else None)
+        right_record = right or (self.db.get_memory(int(right_id)) if right_id is not None else None)
+        if not left_record or not right_record:
+            return self.db.state.response({"error": "left and right records are required"}, ok=False)
+        return self.db.state.response({"comparison": compare_memories(left_record, right_record), "left": left_record, "right": right_record})
+
+    def memory_arbitrate(self, left_id: int, right_id: int, mark_conflict: bool = True, apply: bool = False, **_: Any) -> dict[str, Any]:
+        left = self.db.get_memory(int(left_id))
+        right = self.db.get_memory(int(right_id))
+        if not left or not right:
+            return self.db.state.response({"error": "memory id not found"}, ok=False)
+        comparison = compare_memories(left, right)
+        conflict_id = None
+        if mark_conflict:
+            reason = "; ".join(comparison["reasons"])
+            conflict_id = self.db.record_conflict(int(left_id), int(right_id), left.get("subject") or right.get("subject"), reason, comparison["winner_id"])
+        applied = False
+        if apply and comparison["winner_id"] and comparison["loser_id"] and not comparison["manual_review"]:
+            loser = self.db.get_memory(int(comparison["loser_id"]))
+            if loser and loser.get("protection_level") != ProtectionLevel.LOCKED.value and loser.get("source_type") != SourceType.USER_CONFIRMED.value:
+                applied = self.db.update_memory(int(comparison["loser_id"]), {"status": "superseded"})
+        return self.db.state.response({"comparison": comparison, "conflict_id": conflict_id, "applied": applied})
+
+    def memory_list_conflicts(self, status: str = "open", limit: int = 50, **_: Any) -> dict[str, Any]:
+        conflicts = self.db.list_conflicts(status=status, limit=int(limit))
+        return self.db.state.response({"conflicts": conflicts, "count": len(conflicts)})
+
+    def memory_confirm(self, memory_id: int, source_ref: Optional[str] = None, confidence: float = 1.0, **_: Any) -> dict[str, Any]:
+        memory = self.db.get_memory(int(memory_id))
+        if not memory:
+            return self.db.state.response({"error": "memory id not found"}, ok=False)
+        metadata = dict(memory.get("metadata") or {})
+        metadata["confirmed_from"] = source_ref or "manual"
+        ok = self.db.update_memory(
+            int(memory_id),
+            {
+                "source_type": SourceType.USER_CONFIRMED.value,
+                "confidence": float(confidence),
+                "protection_level": ProtectionLevel.LOCKED.value,
+                "status": "active",
+                "metadata": metadata,
+            },
+        )
+        updated = self.db.get_memory(int(memory_id)) if ok else memory
+        return self.db.state.response({"confirmed": ok, "record": updated})
+
+    def memory_status(self, **_: Any) -> dict[str, Any]:
+        return self.db.state.response(
+            {
+                "db_path": str(self.settings.db_path),
+                "backup_jsonl": str(self.settings.backup_jsonl),
+                "sqlite_vec_available": self.db.state.sqlite_vec_available,
+                "fts5_available": self.db.state.fts5_available,
+                "sqlite_writable": self.db.state.sqlite_writable,
+                "jsonl_backup_active": self.db.state.jsonl_backup_active,
+                "client": self.settings.client,
+                "agent_id": self.settings.agent_id,
+                "workspace": self.settings.workspace,
+                "policy": {
+                    "client_defaults": self.settings.policy.client_defaults,
+                    "default_enabled": self.settings.policy.default_enabled,
+                    "allow_agents": self.settings.policy.allow_agents,
+                    "deny_agents": self.settings.policy.deny_agents,
+                },
+            }
+        )

memory_arbiter_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: memory-arbiter-mcp
+Version: 0.1.0
+Summary: Local MCP memory arbiter with dual timeline conflict handling.
+Author: OpenClaw Project
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.6.0
+Provides-Extra: vec
+Requires-Dist: sqlite-vec>=0.1.1; extra == "vec"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Dynamic: license-file
+
+# memory-arbiter-mcp
+
+**[中文](#中文) | [English](#english)**
+
+---
+
+<a id="english"></a>
+
+## English
+
+A lightweight, fully local MCP Server that gives your AI coding tools a **shared memory store** with built-in conflict arbitration.
+
+Every tool — ZCode, Codex, Cursor, Claude Code — has its own memory. They don't talk to each other. Memory Arbiter fixes this: one SQLite database, all tools read and write through the same MCP protocol, conflicts are resolved by structured rules (not LLM guesswork).
+
+### Features
+
+- **Structured memory write**: `content`, `agent_id`, `workspace`, `tags`, `source_type`, `event_time`, `ingest_time`, `confidence`, `protection_level`, and more.
+- **Source trust levels**: `user_confirmed` > `document_extracted` > `agent_generated` > `unknown`.
+- **Dual timeline arbitration**: resolves conflicts by user confirmation → event time → source trust → ingest time. Every decision comes with an explainable rationale.
+- **Locked protection**: `user_confirmed` memories are automatically locked — no agent can overwrite them.
+- **Client policy system**: per-client enable/disable, agent allow/deny lists for multi-agent governance.
+- **Graceful degradation**: `sqlite-vec` → FTS5 → `LIKE` → JSONL backup. Never crashes.
+- **Zero cloud, zero LLM calls**: pure local SQLite. No Postgres, Redis, or external services.
+
+### Quick Start
+
+**Requirements**: Python 3.11+
+
+```bash
+# Clone
+git clone https://github.com/billy12151/memory-arbiter-mcp.git
+cd memory-arbiter-mcp
+
+# Setup
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e .
+
+# Optional: semantic recall via sqlite-vec
+pip install '.[vec]'
+
+# Run
+memory-arbiter-mcp
+```
+
+### Connect Your Tool
+
+Add to your tool's MCP config (see `examples/` for ready-made templates):
+
+```json
+{
+  "mcpServers": {
+    "memory-arbiter": {
+      "command": "/path/to/memory-arbiter-mcp/.venv/bin/memory-arbiter-mcp",
+      "env": {
+        "MEMORY_ARBITER_CLIENT": "zcode",
+        "MEMORY_ARBITER_AGENT_ID": "zcode-default",
+        "MEMORY_ARBITER_DB_PATH": "~/.local/share/memory-arbiter/memory.sqlite3"
+      }
+    }
+  }
+}
+```
+
+> Change `MEMORY_ARBITER_CLIENT` for each tool (`zcode`, `codex`, `cursor`, `claude-code`). All tools share the same `DB_PATH` — that's the whole point.
+
+> ⚠️ **New session required**: MCP servers are loaded at session startup. Already-open sessions won't see the new tools. Start a fresh session after configuring.
+
+### Client Config Locations
+
+| Client | Config Location |
+|---|---|
+| ZCode | `~/.zcode/v2/` MCP config |
+| Codex CLI | `~/.codex/` MCP config |
+| Claude Code | `.mcp.json` in project root |
+| Cursor | `~/.cursor/mcp.json` |
+
+### MCP Tools
+
+| Tool | Description |
+|---|---|
+| `memory_write` | Write a memory (`source_type=user_confirmed` auto-locks) |
+| `memory_search` | Search memories (FTS5 → LIKE fallback) |
+| `memory_compare` | Compare two memories, returns explanation only |
+| `memory_arbitrate` | Arbitrate conflict, can record result (`apply=true`) |
+| `memory_confirm` | Promote a memory to user-confirmed and locked |
+| `memory_list_conflicts` | List unresolved conflicts |
+| `memory_status` | Show current mode, degradation status, storage paths |
+
+### Data Migration
+
+Moving to a new machine? Just copy the SQLite file:
+
+```bash
+# Copy the database
+cp ~/.local/share/memory-arbiter/memory.sqlite3 /new/machine/~/.local/share/memory-arbiter/
+
+# Reinstall the project (don't copy .venv — rebuild it)
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### Testing
+
+```bash
+python3.11 -m pip install -r requirements.txt
+python3.11 -m pytest
+```
+
+### License
+
+MIT
+
+---
+
+<a id="中文"></a>
+
+## 中文
+
+一个轻量、完全本地运行的 MCP Server，给你的 AI 编程工具提供**共享记忆库**，内置冲突仲裁机制。
+
+你同时用 ZCode、Codex、Cursor、Claude Code——每个工具都有各自的记忆，互不相通。Memory Arbiter 解决这个问题：一个 SQLite 数据库，所有工具通过同一个 MCP 协议读写，冲突由结构化规则仲裁，不依赖大模型。
+
+### 核心能力
+
+- **结构化写入**：`content`、`agent_id`、`workspace`、`tags`、`source_type`、`event_time`、`ingest_time`、`confidence`、`protection_level` 等。
+- **来源可信度**：`user_confirmed` > `document_extracted` > `agent_generated` > `unknown`。
+- **双时间轴仲裁**：按 用户确认 → 事件发生时间 → 来源可信度 → 录入时间 的优先级判定，输出可解释的裁决理由。
+- **锁定保护**：`user_confirmed` 的记忆自动锁定，任何 Agent 都不能自动覆盖。
+- **客户端策略**：按客户端启用/禁用，Agent 级别的 allow/deny 白名单控制。
+- **逐级降级**：`sqlite-vec` → FTS5 → `LIKE` → JSONL 备份，不会崩。
+- **零云依赖、零大模型调用**：纯本地 SQLite，不需要 Postgres、Redis 或外部服务。
+
+### 快速开始
+
+**要求**：Python 3.11+
+
+```bash
+# 克隆
+git clone https://github.com/billy12151/memory-arbiter-mcp.git
+cd memory-arbiter-mcp
+
+# 安装
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e .
+
+# 可选：启用语义召回增强（sqlite-vec）
+pip install '.[vec]'
+
+# 启动
+memory-arbiter-mcp
+```
+
+### 接入工具
+
+在你的工具的 MCP 配置中加入（完整示例见 `examples/` 目录）：
+
+```json
+{
+  "mcpServers": {
+    "memory-arbiter": {
+      "command": "/path/to/memory-arbiter-mcp/.venv/bin/memory-arbiter-mcp",
+      "env": {
+        "MEMORY_ARBITER_CLIENT": "zcode",
+        "MEMORY_ARBITER_AGENT_ID": "zcode-default",
+        "MEMORY_ARBITER_DB_PATH": "~/.local/share/memory-arbiter/memory.sqlite3"
+      }
+    }
+  }
+}
+```
+
+> 每个工具改一下 `MEMORY_ARBITER_CLIENT` 标识（`zcode`、`codex`、`cursor`、`claude-code`），共享同一个 `DB_PATH`——这就是跨工具记忆共享的关键。
+
+> ⚠️ **需要新建会话**：MCP Server 在客户端启动时加载，已经打开的会话不会识别新添加的 Server。配置好后请新建一个会话。
+
+### 客户端配置位置
+
+| 客户端 | 配置文件位置 |
+|---|---|
+| ZCode | `~/.zcode/v2/` 下 MCP 配置 |
+| Codex CLI | `~/.codex/` 下 MCP 配置 |
+| Claude Code | 项目根目录 `.mcp.json` |
+| Cursor | `~/.cursor/mcp.json` |
+
+### MCP 工具
+
+| 工具 | 说明 |
+|---|---|
+| `memory_write` | 写入记忆（`source_type=user_confirmed` 自动锁定） |
+| `memory_search` | 搜索记忆（FTS5 → LIKE 自动降级） |
+| `memory_compare` | 比较两条记忆，只返回解释 |
+| `memory_arbitrate` | 仲裁冲突，自动判定胜者（`apply=true` 时落记录） |
+| `memory_confirm` | 用户确认某条记忆，锁定保护 |
+| `memory_list_conflicts` | 列出未解决的冲突 |
+| `memory_status` | 查看运行状态、模式、降级原因 |
+
+### 数据迁移
+
+换电脑只需拷贝一个文件：
+
+```bash
+# 拷贝数据库
+cp ~/.local/share/memory-arbiter/memory.sqlite3 新电脑:~/.local/share/memory-arbiter/
+
+# 重新安装项目（.venv 不要拷贝，新机器上重建）
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### 测试
+
+```bash
+python3.11 -m pip install -r requirements.txt
+python3.11 -m pytest
+```
+
+### License
+
+MIT

memory_arbiter_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+memory_arbiter/__init__.py,sha256=MK_3xJdjTbJvb7M4a2awe38mp6Q5pLaO9OxCWjbJSCc,57
+memory_arbiter/arbitration.py,sha256=q5kSm5TPenazamzV-rFnZXTTdQbeGhg-lo4HeUF9aNw,4144
+memory_arbiter/config.py,sha256=EitfTJijPPWP5NjVvk9vFk_iH2EEl3iTE9y3-K6Fs0U,2715
+memory_arbiter/db.py,sha256=ilsWjiGVoq39V4VdHAVsTds8Q7gN_9Mw6Wmsou6y5bo,10185
+memory_arbiter/degrade.py,sha256=vLk_gmSMh6wOb56e35kY4pW3SDoJJ2iqtrFwD4x-hhU,1091
+memory_arbiter/models.py,sha256=EIeMRTDRb7qe63GqKeETyuXe0AJp8giv0UXjj-ZVwoo,3048
+memory_arbiter/search.py,sha256=DWFr2a_UmcmobbNRlxq5BXGkCJiTZPhB8usFD5wdHLo,2119
+memory_arbiter/server.py,sha256=VRKfaJ0e39iWgxaLx7ctybeLRq9KQZFYahk7PYSMCGM,3946
+memory_arbiter/tools.py,sha256=xsGGgIAcqcAVYosR05zyiYHrxFgvaTwavnrOYCmAAMs,6233
+memory_arbiter_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=26R1Y1S9Zz9xhwCqKr1BOiXRjk-Z8bSK9lC8wSVaPDk,1067
+memory_arbiter_mcp-0.1.0.dist-info/METADATA,sha256=oA6f70bn16Nlt1ur8_wsvhXOlbJRiVQe0F8aTpSt4ts,7776
+memory_arbiter_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+memory_arbiter_mcp-0.1.0.dist-info/entry_points.txt,sha256=Wkl1Xqd0vLB4Rb3c8sc6Gsgk14TfVmBx4x7pBonPaoI,66
+memory_arbiter_mcp-0.1.0.dist-info/top_level.txt,sha256=FTEDicSQQ34Y267bTtOdFbxwBOSU4jL_ihE4mF5hMBI,15
+memory_arbiter_mcp-0.1.0.dist-info/RECORD,,

memory_arbiter_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

memory_arbiter_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+memory-arbiter-mcp = memory_arbiter.server:main

memory_arbiter_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 billy12151
+
+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.

memory_arbiter_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+memory_arbiter