memory-arbiter-mcp 0.1.0__tar.gz

memory_arbiter_mcp-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,225 @@
+# 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/memory_arbiter/__init__.py

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

memory_arbiter_mcp-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_mcp-0.1.0/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 []),
+    )