OMPA

Obsidian-MemPalace-Agnostic — Universal AI agent memory layer

OMPA gives any AI agent persistent memory with vault conventions, palace navigation, and a temporal knowledge graph.

Credits & Attribution

This project is a synthesis of ideas and code from the AI agent memory community:

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

OMPA combines these into a framework-agnostic package that works with any AI agent runtime.

The Problem

Every AI agent starts empty every session. Important decisions get lost. Context grows expensive. ANKI prompts only get you so far.

The Solution

OMPA gives any AI agent — Claude Code, OpenClaw, Codex, Gemini CLI, or any custom agent — persistent, structured memory that:

• Never forgets a decision (vault + knowledge graph)
• Knows where things belong (15 message types with routing hints)
• Survives context compaction (verbatim storage, no summarization loss)
• Works offline (local sentence-transformers, zero API cost)

Quick Start

pip install ompa

# Initialize a vault
ao init ./workspace

# Run your agent session, then:
ao session-start     # ~2K token context injection
ao classify "We decided to go with Postgres"   # Route to right folder
ao search "authentication decisions"           # Semantic search
ao kg-query Kai       # Query the knowledge graph
ao wrap-up            # Session summary + save to vault

How It Works

Three-Layer Memory Architecture

┌─────────────────────────────────────────────────────────┐
│  Layer 1: Vault (human-navigable markdown)              │
│  brain/  work/  org/  perf/  ← obsidian-mind structure  │
├─────────────────────────────────────────────────────────┤
│  Layer 2: Palace (agent-accessible metadata)            │
│  wings → rooms → drawers (vault file references)       │
│  halls: facts, events, discoveries, preferences         │
│  tunnels: cross-wing connections                       │
├─────────────────────────────────────────────────────────┤
│  Layer 3: Knowledge Graph (temporal triples)             │
│  SQLite: subject → predicate → object + validity window │
│  Query entity history at any point in time             │
└─────────────────────────────────────────────────────────┘

5 Lifecycle Hooks

15 Message Types

DECISION, INCIDENT, WIN, ONE-ON-ONE, MEETING, PROJECT-UPDATE, PERSON-INFO, QUESTION, TASK, ARCHITECTURE, CODE, BRAIN-DUMP, WRAP-UP, STANDUP, UNKNOWN — each with routing hints that automatically file things in the right place.

Semantic Search (Zero API Cost)

Uses sentence-transformers (all-MiniLM-L6-v2) locally. No OpenAI/Anthropic API calls for search.

Architecture

ompa/
├── core.py              # Ompa main class
├── vault.py             # Vault management (brain/work/org/perf)
├── palace.py            # Palace metadata (wings/rooms/drawers)
├── knowledge_graph.py   # Temporal KG (SQLite triples)
├── hooks.py             # 5 lifecycle hooks
├── classifier.py        # 15 message types
├── semantic.py          # Local semantic search
├── mcp_server.py        # MCP protocol server (14 tools)
└── cli.py               # 15 CLI commands

MCP Server (14 Tools)

Works with Claude Desktop, Cursor, Windsurf natively:

# Claude Desktop
claude mcp add ompa -- python -m ompa.mcp_server

Tools: ao_session_start, ao_classify, ao_search, ao_kg_query, ao_kg_add, ao_kg_stats, ao_palace_wings, ao_palace_rooms, ao_palace_tunnel, ao_validate, ao_wrap_up, ao_status, ao_orphans, ao_init

Python API

from ompa import Ompa

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

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

# 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
ao.palace.create_wing("Orion", type="project")
ao.palace.create_tunnel("Kai", "Orion", "auth-migration")
traversal = ao.palace.traverse("Orion", "auth-migration")

CLI Commands

ao init          ao status      ao session-start  ao classify
ao search        ao orphans     ao wrap-up        ao wings
ao rooms         ao tunnel      ao kg-query       ao kg-timeline
ao kg-stats      ao validate    ao rebuild-index

Framework Agnostic

Unlike MemPalace (Claude Code + MCP only) or obsidian-mind (Claude Code hooks only), OMPA works with any AI agent:

Installation

pip install ompa              # Core (vault, palace, KG, CLI)
pip install ompa[semantic]    # + sentence-transformers for semantic search
pip install ompa[all]         # All optional dependencies

Requires Python 3.10+.

Why "Agnostic"?

Because memory should not be coupled to your agent framework. Build once, use anywhere. The "Universal" angle is the moat — not just another Claude Code plugin.

Comparison

License

MIT — Micap AI