OPEM

One Personal Evolving Memory System

English | 简体中文

Live Sites showcase · Owner-only deployment

OPEM, short for One Personal Evolving Memory System, aggregates conversations, durable observations, and tool outcomes from Codex instances across multiple machines, consolidates them into long-term knowledge, supports contextual recall, and evolves as its owner continues to use it.

MVP scope: trusted LAN HTTP, one shared server, SQLite or PostgreSQL, no authentication or TLS.

• Cross-machine collection — multiple Codex CLI, Desktop, or Remote hosts write to one Memory Server.
• MCP-first integration — submit, recall, report verified outcomes, request route advice, record controlled path ablations, archive complete chat, and check health.
• Raw history plus durable Memory — the complete transcript remains available while reusable knowledge is compressed separately.
• Hybrid recall — exact phrase, BM25, fuzzy, metadata, and optional vector similarity are fused with weighted RRF and deduplicated with MMR.
• Session Trace — group each Session into user-led request paths and show Codex/tool nodes with measured or estimated timing.
• Tool Call Groups — build usage profiles from inputs/outputs, language and keywords, then cluster functionally similar tools with explainable similarity and faceted filters.
• Tool archive and FAQ — successful tools become recallable context; failed tools become evidence-backed FAQ entries.
• Daily summaries — browse decisions, learnings, unresolved problems, and Memory highlights on a calendar.
• Small deployment footprint — FastAPI, SQLAlchemy, one Worker, server-rendered pages, and SQLite or PostgreSQL/pgvector.

The editable Mermaid source is available at docs/architecture.mmd.

The server keeps raw ChatMessage and Observation records independent from generated Memory. Every generated Memory retains source Observation and Session links.

Requirements: Python 3.12 or newer.

git clone git@github.com:dawncc/OPEM.git
cd OPEM
python -m venv .venv

Activate the environment and install the project:

# Linux / macOS
source .venv/bin/activate
pip install -e ".[dev]"

# Windows PowerShell
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Initialize SQLite:

# Linux / macOS
export DATABASE_URL="sqlite:///./demo.db"
python -c "from memory_server.db import Base,engine; import memory_server.models; Base.metadata.create_all(engine)"

# Windows PowerShell
$env:DATABASE_URL="sqlite:///./demo.db"
.\.venv\Scripts\python -c "from memory_server.db import Base,engine; import memory_server.models; Base.metadata.create_all(engine)"

Run these in two terminals with the same DATABASE_URL:

# Linux / macOS
codex-memory-server
codex-memory-worker

# Windows PowerShell
.\.venv\Scripts\codex-memory-server
.\.venv\Scripts\codex-memory-worker

Optionally load demonstration data:

.\.venv\Scripts\python scripts\seed_demo.py
.\.venv\Scripts\python scripts\seed_conversation_demo.py

Open http://127.0.0.1:8000.

The Compose deployment starts PostgreSQL/pgvector, the API/UI server, and the Worker.

cp .env.example .env
cd deploy
docker compose up --build -d

Open http://<server-lan-ip>:8000. PostgreSQL is only exposed to the internal Compose network.

Install the package on every Codex machine:

pipx install .

Add the MCP server to $CODEX_HOME/config.toml:

[mcp_servers.codex_memory]
command = "codex-memory-mcp"
args = ["--server", "http://192.168.1.100:8000"]
startup_timeout_sec = 30

Copy skill/codex-memory to $CODEX_HOME/skills/codex-memory, restart Codex, and call memory_health.

The Skill instructs Codex to:

1. recall relevant project history before substantial work;
2. save durable decisions, learnings, problems, and solutions;
3. archive the complete conversation and all available tool results;
4. include duration_ms when exact timing is available;
5. submit a structured summary before session end or compaction.
6. report whether recalled memories were helpful, irrelevant, or harmful.

The MVP keeps the business API intentionally small:

Main UI routes:

• / — overview
• /search — Memory search
• /calendar — daily Memory calendar
• /traces — Session request paths and timing
• /tools — tool execution archive
• /faq — failed-tool FAQ
• /sessions/<id> — complete conversation

1. Capture — save the raw Observation or complete chat first.
2. Compress — use an optional OpenAI-compatible model, or deterministic rule compression when no LLM is configured.
3. Consolidate — merge only compatible Memory types and keep every source link.
4. Retrieve — combine exact phrase, BM25, fuzzy, metadata, and optional embedding results.

Successful tools become tool_success Memory. Failed tools become separate tool_failure_faq Memory so similar success and failure output can never be consolidated together. Unknown outcomes are archived without promotion.

Recall outcomes form a bounded evolution loop: explicit feedback calibrates ranking confidence without changing application code or model weights. See the self-evolution design for the safety boundary and roadmap.

Pass top-level duration_ms on a memory_chat_submit message when exact timing is known. Trace renders exact timing in blue. Older messages fall back to the adjacent message timestamp and are explicitly marked as estimates. Active duration excludes idle time between separate user requests.

If a remote host cannot route directly to the LAN server, create a reverse SSH tunnel from the Memory Server machine:

ssh -N -R 18000:127.0.0.1:8000 <remote-host>

Configure the remote MCP bridge with --server http://127.0.0.1:18000. The included scripts/test_remote_codex.sh validates health, chat submission, successful/failed tool archival, FAQ generation, and recall from a real remote Codex process.

A directly routable LAN, VPN, or private network address is preferred for permanent deployment; the reverse tunnel only exists while its SSH process is running.

MCP/Skill-only capture depends on Codex choosing to call a tool and can miss ordinary requests. Install deterministic lifecycle hooks on every Codex host:

python scripts/install_codex_hooks.py --server http://192.168.1.100:8000

The installer preserves existing hooks and adds UserPromptSubmit, PostToolUse, Stop, and PreCompact capture. User prompts, tool results, and final assistant messages become visible immediately; Stop also creates an Observation for asynchronous Memory consolidation. The standard-library-only client queues failed deliveries under $CODEX_HOME/codex-memory/pending.jsonl and retries them on the next lifecycle event.

After installation, open /hooks in Codex, review and trust the new definitions, then start a new task. The home page refreshes its live-session list every five seconds. hooks/session-end.py remains only as a legacy compatibility entry point.

Preview completed turns stored under $CODEX_HOME/sessions, then synchronize them:

codex-memory-sync --server http://192.168.1.100:8000 --since 2026-07-01 --dry-run
codex-memory-sync --server http://192.168.1.100:8000 --since 2026-07-01

Only turns with a task_complete event are imported. The backfill uses the same turn, tool-call, and event identifiers as the real-time hooks, so reruns and hook/backfill overlap are idempotent. Legacy rows without event identifiers use role/content occurrence matching as a compatibility fallback. Rollout JSONL remains a best-effort local import source; real-time hooks are the supported primary capture path.

• Cost control and context compression for multi-turn tasks (Chinese)
• Zero-sample execution-path evolution (Chinese)

packages/memory-common/   Shared schemas, settings, pending queue
packages/memory-server/   FastAPI, SQLAlchemy, recall, Trace, Jinja2 UI
packages/memory-worker/   compression, consolidation, embeddings, daily summaries
packages/memory-mcp/      local stdio MCP-to-HTTP bridge
skill/codex-memory/       Codex workflow Skill
hooks/                    Stop / PreCompact fallback hook
migrations/               Alembic migrations
deploy/                   Docker Compose deployment
scripts/                  seed and remote validation scripts
tests/                    unit and integration tests
docs/images/              README screenshots

pip install -e ".[dev]"
pytest

Current test coverage includes chat preservation, Chinese/English retrieval, recall isolation, pending retries, tool outcome classification, TaskRun/DAG derivation, evidence aggregation, causal-path guards, strategy gates, FAQ construction, Worker consolidation boundaries, Trace timing, and HTML escaping.

This MVP assumes a trusted private network. It does not implement TLS, authentication, device tokens, tenant isolation, or automatic redaction. Add those controls before exposing the service beyond a trusted LAN or VPN.

Copyright (c) 2026 dawncc.

This project is open-source software licensed under the MIT License. You may use, copy, modify, merge, publish, distribute, sublicense, and sell copies subject to the license terms.