convez.ai
MCP ServerAutomaçãoAvançado
xpajonx

OpenEmpiric

xpajonx/openempiric

Memória persistente baseada em eventos para agentes de codificação IA

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que funciona como memória de longo prazo para agentes de IA em sessões de codificação. Captura automaticamente decisões arquiteturais, experimentos e resultados em um ledger de eventos, estruturando-os como um grafo de conhecimento local que guia futuras sessões sem necessidade de atualização manual.

Instalação

$npx convez-ai xpajonx/openempiric

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
10
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 2 meses
Versão
v1.1.0
Issues abertas
0
Contribuidores
5

Casos de uso

  • Construir memória acumulativa em projetos de desenvolvimento com agentes IA
  • Evitar que agentes cometam os mesmos erros em sessões futuras
  • Documentar automaticamente decisões arquiteturais e trade-offs através de conversas

Veredito

Ferramenta sofisticada para times que trabalham com agentes IA em coding. O conceito de event-sourcing para capturar conhecimento de sessões é sólido, mas requer integração cuidadosa e compreensão da arquitetura interna. Recomendado para quem busca verdadeira memória persistente em fluxos de IA, não apenas para prototipagem rápida.

README

A tradução para o português deste README ainda está na fila.


What is OpenEmpiric?

OpenEmpiric (OEM) is a local-first, agent-first learning runtime. It acts as long-term memory for your AI coding agents, capturing crucial architectural decisions, experiments, tradeoffs, failures, and outcomes directly from your developer-agent conversations. It stores this knowledge in an event-sourced ledger and structures it as a local knowledge graph, making it immediately available to guide future coding sessions.

Instead of writing and updating guidelines manually, you simply work with your agent. OEM automatically builds your project's memory map, preventing your agent from making the same mistake twice.


How it Works

OpenEmpiric shifts the model of AI coding sessions from a simple wrapped process to an active knowledge infrastructure. It is best explained through two layers: the user mental model (why it exists) and the internal runtime flow (how it works).

1. User Mental Model (Why OEM Exists)

Rather than just receiving static prompts, a highly productive AI coding agent relies on three balanced pillars:

  • Developer Intent: The immediate task, constraints, and goals you provide.
  • Project Workflows (e.g., AGENTS.md / CLAUDE.md): Guidelines detailing how the project is structured, run, and styled.
  • Project Memory (e.g., .oem/): The persistent knowledge layer managed by OpenEmpiric, recording what has been learned (prior decisions, resolved failures, validated designs).
graph TD
    Intent["Developer Intent<br>(What to do)"] --> Agent("Coding Agent")
    Workflows["Project Workflows<br>(How to work - e.g., AGENTS.md)"] --> Agent
    Memory["Project Memory (.oem/)<br>(What we've learned)"] --> Agent

2. Internal Runtime & Tooling Flow (How OEM Works)

The .oem/ directory at the project root acts as the center of gravity. During execution, the coding agent actively queries this memory infrastructure using MCP tools rather than just reading static startup files.

graph TD
    Developer(["Developer"]) -->|"Runs oem run agent"| OEM["OpenEmpiric Runtime"]
    OEM -->|"1. Restore State"| Folder[(".oem/ Project Memory")]
    Folder -.->|"Injected Context"| Agent("Coding Agent")
  
    Developer ---|"2. Normal Work Session"| Agent
  
    Agent ---|"3. Active MCP Queries<br>(knowledge_search, explain_concept, etc.)"| Folder
  
    Agent -->|"4. Exits"| OEM
    OEM -->|"5. Reflects Transcripts & Diffs"| Ledger[(".oem/ Event Ledger")]
    Ledger -->|"Updates"| Registry["concept_registry.json"]
    Ledger -->|"Generates"| Wiki[".oem/wiki/ Concept Wiki"]
    Registry -->|"Sync"| Folder
    Wiki -->|"Sync"| Folder

Key Features

  • 🧠 Zero-Config Agent Memory: No manual updates or prompt-engineering required. OEM learns continuously in the background.
  • 🔄 Automatic Reflection: Analyzes chat transcripts and file diffs to automatically extract new concepts, decisions, experiments, and root causes of failures.
  • 🛡️ Secure File System Guards: SFS wrapper protects the host workspace with strict path-traversal limits and truncation protection (prevents agents from accidentally erasing large files).
  • 🔎 Local RAG Retrieval: Perform hybrid vector-BM25 search queries across your project's memory repository locally.
  • 📚 Materialized Wiki: Auto-generates clean, human-readable markdown documentation in .oem/wiki/ as the knowledge graph evolves.

Quick Start

1. Install Globally

Install the unified oem CLI runtime globally using uv with semantic retrieval support:

uv tool install "git+https://github.com/xpajonx/openempiric.git#subdirectory=packages/oem-knowledge[semantic]"

For a lighter BM25-only install, you can omit [semantic], but the default user path assumes semantic retrieval is available when possible.

2. Setup Agent Integration

Register your preferred agent integration with OpenEmpiric.

For terminal-based workstation environments (like OpenCode):

oem setup opencode

For desktop-based non-terminal environments (like Codex App):

oem setup codex-app

3. Launch a Session

From any project directory, launch a managed session:

mkdir demo-project
cd demo-project
oem run opencode

oem run opencode bootstraps the project-local .oem/ memory folder automatically and starts a managed session.

(Note: For Codex App, standard MCP tools are configured automatically. The agent uses the knowledge_session_end conversational tool to commit and persist learnings at the end of a session).

4. Diagnose Problems

Verify your workspace integration and bridge health:

oem doctor

Supported Agents & Custom Adapters

OpenEmpiric officially supports the following agent runtimes out-of-the-box:

  • OpenCode: Workstation-level integration, native plugins, and session supervisor for terminal environments.
  • Antigravity: Terminal co-pilot and command-line companion integration.
  • Codex App: First-class MCP-based non-terminal desktop runtime, configured automatically via the WSL bridge architecture (oem setup codex-app).

Extensibility: Write Your Own Adapter!

You can easily extend OpenEmpiric to support other environments (such as Claude Code, Cursor, or your own proprietary CLI agent). All you need to do is subclass the base adapter:

from oem_knowledge.adapters.base import BaseAdapter
from oem_knowledge.adapters.registry import register_adapter

@register_adapter("my-custom-agent")
class MyCustomAgentAdapter(BaseAdapter):
    def verify_mcp(self) -> bool:
        # Check if agent is installed and configured
        return True

    def parse_transcript(self, transcript_path) -> str:
        # Extract dialogue text from agent logs
        return transcript_path.read_text()

Refer to the Adapter Architecture Guide and Adapter Specification for details.


CLI Command Reference

CommandCategoryDescription
oem run <agent>UserRun a managed coding agent session with context injection.
oem setup <target>UserConfigure and register integrations (opencode or codex-app).
oem doctorUserVerify workspace health, plugin links, model warmup, and agent integrations.
oem search <query>UserSearch the project knowledge base using automatic/BM25/hybrid retrieval.
oem healthUserScan the workspace for stale concepts, duplicates, and contradicting knowledge.
oem config retrieval <mode>UserView or set retrieval strategy toauto, bm25, or hybrid.
oem initAdminInitialize the.oem/ memory repository in the current workspace.
oem migrateAdminMigrate legacy.harness/ directory to .oem/ format.
oem mcpAdminStart the background MCP tool server for non-terminal runtimes.
oem merge <id1> <id2>AdvancedManually merge two overlapping or duplicate concepts.
oem rebuildAdvancedReplay the event store log to rebuild the entire concept registry.
oem reflectAdvancedDry-run reflection and concept extraction from raw transcripts.

MCP Tool Reference

When integrated as an MCP server, OpenEmpiric exposes the following tools to the AI agent to support context injection, memory retrieval, task tracking, and session commitment:

Core Retrieval & Exploration

  • knowledge_search(query: str, k: int, project: str): Perform hybrid semantic and keyword search across concepts.
  • knowledge_explain_concept(concept_id: str, project: str): Retrieve full markdown documentation, canonical name, and recent learnings/evidence for a concept.
  • knowledge_graph_query(concept_id: str, direction: str, project: str): Query semantic relationships (incoming/outgoing/both) between concept nodes.
  • knowledge_stats(project: str): View high-level statistics of the knowledge base and local vector database size.

Session Lifecycle & Telemetry

  • knowledge_session_end(project: str, conversation_text: str, session_id: str): Ends the session, runs transcript analysis and git diff extraction to update concept records, and commits all changes. Returns a clean markdown summary report.
  • knowledge_usage_report(concepts_used: list[str], concepts_ignored: list[str], decisions: list[str], project: str): Reports telemetry regarding concept usage and decision alignment during a session.
  • knowledge_health_check(stale_sessions: int, similarity_threshold: float, project: str): Propose duplicate merges, find stale concepts, and detect contradictions.

Task / TODO Management

  • oem_todo_read(workdir: str): View the active session task checklist from .oem/state/todos.json.
  • oem_todo_write(items: str, workdir: str): Overwrite the todo list with a new JSON list of items.
  • oem_todo_advance(item_id: str, status: str, workdir: str): Update a task's status (pending, in_progress, completed) and automatically cycle next items.

Concept Management & Verification

  • knowledge_consolidate(project: str): Identify and merge duplicate and overlapping concept nodes automatically.
  • knowledge_merge_concepts(project: str, primary_id: str, secondary_id: str): Manually merge a secondary concept into a primary concept.
  • knowledge_lint(project: str, max_parallel: int, fix: bool): Find broken/orphan concept links and automatically heal matching aliases.

How It Learns: High-Value Cues

OEM works automatically, but it extracts the highest-quality knowledge when developers state reasoning and results explicitly during a conversation.

Concept SignalBetter (OEM Captures Rationale)Worse (Vague/Context-Free)
Decisions"We decided to use TypeScript because Python startup latency caused MCP timeouts.""Use TypeScript."
Failures"The pagination job failed because the pagination cursor was not reset between retries.""Pagination is broken."
Tradeoffs"We chose client-side caching to avoid Redis dependency, accepting up to 5 minutes of stale data.""Use client-side cache."
Experiments"We tested BM25 vs hybrid search. Hybrid scored 23% higher on recall@5, so we made it default.""Hybrid search works better."
Outcomes"Restructuring the DB index reduced retrieval latency from 5.5s to 450ms.""Looks faster now."

Check out the Best Practices Guide for more details.


Repository Anatomy

  • packages/oem-knowledge — Core RAG logic, SQLite event database, extraction services, and CLI.
  • plugins — Native TypeScript plugins for IDE/workstation agent integrations.
  • docs — Complete specifications, architecture details, and lifecycle logs.
Ver o original no GitHub

Bom para

Relacionados