ompa 1.0.6

Universal AI agent memory layer — vault + palace + temporal knowledge graph

OMPA

Universal AI Agent Memory Layer

Vault · Palace · Temporal Knowledge Graph

---

Obsidian-MemPalace-Agnostic — Give any AI agent persistent memory in one pip install. Works with Claude Code, OpenClaw, Codex, Gemini CLI, LangChain, or any custom agent.

pip install ompa
ao init && ao session-start

96.6% R@5 on LongMemEval using verbatim storage — no summarization loss, no API cost for search.

---

Why OMPA?

Every AI agent starts empty every session. Important decisions get lost. Context grows expensive. Summaries lose nuance.

OMPA solves all three:

Problem	OMPA's Answer
Lost decisions	Vault — every significant event persisted as markdown
Expensive context	5 lifecycle hooks with token budgets (~2K at start, ~100 per message)
Summarization loss	Verbatim storage — proven 96.6% R@5 on LongMemEval
Framework lock-in	Works with any Python agent, any LLM
API cost for search	Local sentence-transformers — zero per-query cost

---

Three-Layer Architecture

flowchart TB
    agent(["🤖 AI Agent"])

    subgraph vault["Layer 1 · Vault"]
        v["brain/ · work/ · org/ · perf/\nhuman-navigable markdown notes"]
    end

    subgraph palace["Layer 2 · Palace"]
        p["wings → rooms → drawers\nhalls · facts · events · tunnels"]
    end

    subgraph kg["Layer 3 · Knowledge Graph"]
        k["subject → predicate → object\nSQLite · validity windows · timeline"]
    end

    agent <-->|"session_start · user_message · stop"| vault
    vault <--> palace
    palace <--> kg

Layer	What it stores	Who reads it
Vault	Markdown notes — decisions, incidents, wins, learnings	Humans + agents via ao search
Palace	Structured metadata — wings, rooms, drawers, fact halls	Agent retrieval acceleration
Knowledge Graph	Temporal triples with validity windows	ao kg-query — any entity, any point in time

---

Quick Start

1. Install

pip install ompa          # Core only
pip install ompa[all]     # Includes local semantic search

2. Initialize a vault

ao init              # Create vault structure
ao status            # Verify everything looks good

3. Use in a session

ao session-start                              # ~2K token context injection
ao classify "We decided to go with Postgres"  # Routes to right folder automatically
ao search "authentication decisions"          # Local semantic search, zero API cost
ao kg-query Kai                               # Query the knowledge graph
ao wrap-up                                    # Session summary + save to vault

4. Python API

from ompa import Ompa

ao = Ompa(vault_path="./workspace")

# Lifecycle
context = ao.session_start()              # Returns ~2K token context string
hint = ao.handle_message("We won the enterprise deal!")
ao.post_tool("write", {"file_path": "work/active/auth.md"})
ao.stop()

# Semantic search
results = ao.search("authentication decisions", wing="Orion")

# Knowledge graph
ao.kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
triples = ao.kg.query_entity("Kai")
timeline = ao.kg.timeline("Orion")

# Palace navigation
ao.palace.create_wing("Orion", type="project")
ao.palace.create_tunnel("Kai", "Orion", "auth-migration")

---

Features

5 Lifecycle Hooks

Hook	Token Budget	Fires When
session_start	~2,000	Session begins — full context injection
user_message	~100	Each incoming user message
post_tool	~200	After each tool call
pre_compact	~100	Before context compaction
stop	~500	Session ends — wrap-up and persist

15 Message Types

Auto-classified and routed to the right vault folder:

DECISION · INCIDENT · WIN · LOSS · BLOCKER · QUESTION · SUGGESTION · REVIEW · BUG · FEATURE · LEARN · RETROSPECTIVE · ALERT · STATUS · CHORE

ao classify "We decided to go with Postgres over MySQL"
# → MessageType.DECISION → vault/work/decisions/2026-05-07-postgres.md

MCP Server (15 Tools)

Plug directly into Claude Desktop, Cursor, or Windsurf with one command:

claude mcp add ompa -- python -m ompa.mcp_server

Tool	Description
ao_session_start	Inject full memory context (~2K tokens)
ao_classify	Route a message to the right vault folder
ao_search	Semantic search across vault
ao_kg_query	Query knowledge graph for an entity
ao_kg_add	Add a triple to the knowledge graph
ao_kg_stats	Knowledge graph statistics
ao_palace_wings	List all wings
ao_palace_rooms	List rooms in a wing
ao_palace_tunnel	Create/traverse cross-wing tunnel
ao_validate	Validate vault structure
ao_wrap_up	Session summary + persist
ao_status	Vault health status
ao_orphans	Detect orphaned notes
ao_init	Initialize a new vault
ao_stop	Clean session shutdown

Dual-Vault Mode

Isolate team/org content from personal or private notes:

from ompa import Ompa, DualVaultConfig, IsolationMode

config = DualVaultConfig(
    shared_vault="./team-vault",
    personal_vault="./private-vault",
    mode=IsolationMode.AUTO,
)
ao = Ompa(config=config)

---

CLI Reference

ao init              Initialize a new vault
ao status            Health check and stats (shows installed vs latest version)
ao session-start     Inject memory context (use at session start)
ao classify <msg>    Classify and route a message
ao search <query>    Semantic search
ao orphans           Detect orphaned notes
ao wrap-up           Session summary and save
ao wings             List palace wings
ao rooms <wing>      List rooms in a wing
ao tunnel            Create/traverse cross-wing tunnel
ao kg-query <entity> Query knowledge graph
ao kg-timeline <e>   Entity timeline
ao kg-stats          Knowledge graph statistics
ao validate          Validate vault structure
ao rebuild-index     Rebuild the semantic index
ao upgrade           Upgrade ompa to the latest version from PyPI
ao doctor            Full health check table (version, vault, KG, index, orphans)
ao migrate-vault     Apply pending vault schema migrations

---

Framework Compatibility

Agent Framework	Integration Method
Claude Code	Python API + MCP server
OpenClaw	Python API + MCP server
Codex	Python API + MCP server
Gemini CLI	Python API + MCP server
LangChain	Python API
Custom agents	Python API

---

Comparison

Feature	OMPA	MemPalace	obsidian-mind
Framework support	Any	Claude Code only	Claude Code only
Memory layers	Vault + Palace + KG	Palace + KG	Vault only
Semantic search	Local (free)	ChromaDB API	QMD (paid)
Temporal KG	SQLite ✓	SQLite ✓	✗
MCP server	15 tools	15 tools	✗
CLI	14 commands	✗	✗
Lifecycle hooks	5	3	3
Message types	15	15	5
Verbatim storage	✓	✓	✗
Multi-agent	✓	✗	✗
Dual-vault isolation	✓	✗	✗

---

Installation Options

# Core (vault + palace + KG + CLI + MCP server)
pip install ompa

# With local semantic search (adds sentence-transformers + numpy)
pip install ompa[all]

# Development
pip install ompa[dev]

# From source
git clone https://github.com/jmiaie/MicapAiLabs && cd MicapAiLabs/ompa
pip install -e ".[all]"

Requires Python 3.10+.

---

Package Structure

ompa/
├── core.py              # Ompa main class — lifecycle, hooks, dual-vault
├── vault.py             # Vault management (brain/work/org/perf)
├── palace.py            # Palace metadata (wings/rooms/drawers/halls/tunnels)
├── knowledge_graph.py   # Temporal KG (SQLite triples + validity windows)
├── hooks.py             # 5 lifecycle hooks + HookManager
├── classifier.py        # 15 message types with auto-routing
├── semantic.py          # Local semantic search (lazy model loading)
├── mcp_server.py        # MCP protocol server (15 tools)
├── config.py            # Dual-vault configuration
└── cli.py               # typer CLI (14 commands)

---

Credits & Attribution

OMPA is a synthesis of ideas from the AI agent memory community:

• MemPalace by Kyle Corbitt — palace metaphor (wings/rooms/drawers), temporal KG design, and verbatim storage approach (96.6% R@5 on LongMemEval)
• obsidian-mind — vault structure (brain/work/org/perf), wikilink conventions, frontmatter validation, session lifecycle patterns
• Claude Code / Anthropic — hook patterns and agent-tool interaction models
• OpenClaw — framework-agnostic agent runtime that inspired the "universal" design goal

---

License

MIT — Micap AI