PCE Memory

Process-Context Engine (PCE) - MCP Server for Context-Aware Memory & Retrieval

Overview

PCE Memoryは、LLMエージェントやアプリケーションに文脈記憶・検索・統合機能を提供するMCPサーバーです。

Key Features

• 🔒 Boundary-first Security: スコープベースの境界管理とRedact-before-send
• 🧠 Dual-phase Memory: LCP (長期記憶) + AC (短期記憶) の二相アーキテクチャ
• 🔍 Hybrid Search: FTS + VSS のハイブリッド検索 (r, S, g 関数)
• 📊 DuckDB Storage: 組み込みDuckDBによる高速ローカルストレージ
• 🎯 MCP Protocol: Model Context Protocol v1.0.4 準拠
• 🛡️ Law-Driven Engineering: fp-ts/io-ts によるType-safe & Property-based Testing

Benchmark Results

pce-memory's hybrid search pipeline is evaluated across three dimensions: search quality, scalability, and latency.

Search Quality (Ablation Study)

Hybrid search combines the precision of keyword matching with the semantic understanding of vector search, achieving +41.7pp recall over text-only and +4.6pp over vector-only.

Provenance-Aware Reranking

The g() reranking function leverages claim provenance quality to improve result ordering:

Measured at 150 claims (golden + synthetic noise). Claims with richer provenance (actor, notes) are ranked higher.

Scalability

Latency Profile

All operations are well below the 100ms human perception threshold. Run pnpm benchmark to reproduce (requires apps/pce-memory/external/assay-kit submodule).

Project Structure

pce-memory/
├── apps/
│   └── pce-memory/          # MCP server implementation
├── packages/
│   ├── pce-boundary/        # Boundary validation & redaction
│   ├── pce-embeddings/      # Embedding provider abstraction
│   ├── pce-policy-schemas/  # YAML policy schemas
│   └── pce-sdk-ts/          # TypeScript client SDK
├── docs/                    # Documentation
│   ├── pce-memory-vision.md
│   ├── core-types.md
│   ├── mcp-tools.md
│   ├── boundary-policy.md
│   └── activation-ranking.md
├── scripts/                 # Development and local validation helpers
└── validation/              # Local validation tasks and result artifacts

Quick Start

Prerequisites

• Node.js: ≥ 22.18.0 (LTS)
• pnpm: ≥ 9.0.0

Installation

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run property-based tests
pnpm test:pbt

Running the MCP Server

# Start MCP server (stdio transport)
cd apps/pce-memory
pnpm dev

Development Workflow

# Watch mode (auto-reload on file changes)
pnpm dev

# Type checking
pnpm typecheck

# Linting
pnpm lint
pnpm lint:fix

# Formatting
pnpm format
pnpm format:check

# Clean build artifacts
pnpm clean

Local Architecture Validation with Ollama

The repository includes a documented local validation workflow for architecture experiments using Ollama and qwen3.5:122b-a10b.

# Interactive Codex against Ollama
pnpm local:codex

# Interactive Claude Code through Ollama launch integration
pnpm local:claude

# Canonical smoke task
pnpm local:validation:smoke

See docs/local-validation-ollama.md for machine assumptions, launch recipes, known limitations, and result capture conventions.

MCP Tools

PCE Memoryは以下のMCPツールを提供します：

詳細は docs/mcp-tools.md を参照してください。

Recommended V2 Flow

現在の推奨フローは次のとおりです。

observe -> distill -> promote -> activate(intent) -> feedback -> rollback

• observe は raw-only です。durable claim は inline で作りません。
• upsert は already-distilled な durable knowledge の escape hatch です。
• scope=session と boundary_class=secret の durable 書き込みは避け、observe を使います。

Observation（pce_memory_observe）の保持とセキュリティ（要点）

• Observation は短期TTLで保持し、期限後は content をスクラブ（NULL化）する運用を推奨します。
• PCE_OBS_TTL_DAYS / PCE_OBS_TTL_DAYS_MAX で TTL を調整できます。
• PCE_OBS_MAX_BYTES で content の最大バイト数を制限できます（既定 65536）。
• PCE_OBS_STORE_MODE（raw|redact|digest_only）で保存モードを調整できます（既定 redact）。
• secret を検知した場合は fail-safe として content を保存せず、抽出もスキップします（詳細は docs/mcp-tools.md の observe を参照）。

Architecture

PCE Memoryは以下のコアモジュールで構成されます：

• Observation Store: raw observation を TTL 付きで保持し、必要に応じて redact / digest-only を適用
• Promotion Pipeline: distill -> promote -> rollback で durable claim を管理
• Retriever: activate で intent-aware に文脈を検索・活性化 (Query + LCP -> AC)
• Critic: durable claim を評価・更新 (Feedback -> utility/confidence/recency)

詳細は docs/pce-memory-vision.md を参照してください。

Testing Strategy

Law-Driven Engineering (LDE)

PCE Memoryは**Law-Driven Engineering (LDE)**原則に従います：

1. Type-driven Design: fp-ts/io-ts によるBranded Types
2. Property-based Testing: fast-checkによる不変条件検証
3. Errors as Values: Either/TaskEither による明示的エラー処理
4. Detroit School TDD: 実際のコンポーネント連携をテスト

Formal Verification

• pnpm formal:tla — TLA+ (TLC)。tlc が無い場合は Docker ghcr.io/tlaplus/tlaplus を自動利用。
• pnpm formal:alloy — Alloy (SAT4J)。初回実行時に jar を .cache/formal に取得し Java で全コマンドを走査。
• pnpm formal:all — 上記まとめ実行。

Test Commands

# All tests (unit + property-based)
pnpm test

# Property-based tests only
pnpm test:pbt

# With coverage (≥ 80% required)
pnpm test --coverage

# Watch mode
pnpm test:watch

詳細は packages/pce-boundary/test/README.md を参照してください。

Contributing

Code Quality Gates

Commit Convention

feat: Add new feature
fix: Fix bug
docs: Update documentation
test: Add tests
refactor: Refactor code
chore: Update build config

License

MIT License - see LICENSE for details

Documentation

• Vision & Mission
• Usefulness Review (JA)
• Core Types
• Local Validation with Ollama
• MCP Tools
• Boundary Policy
• Activation Ranking
• DuckDB Schema
• Search Extensions

Related Projects

• Model Context Protocol
• fp-ts
• io-ts
• fast-check
• DuckDB

Acknowledgments

Built with ❤️ by CAPHTECH, following Law-Driven Engineering principles and inspired by:

• Ernst Cassirer's Philosophy of Symbolic Forms
• Actor-Network Theory (ANT)
• Buddhist concepts of dependent origination (縁起)

Status: 🚧 Work in Progress (MVP Phase)