{"id":"928fea3d-d728-487c-9437-3fbff8032e11","slug":"oghma","kind":"mcp","name":"oghma","summary":"Persistent memory for AI coding assistants. Mines transcripts, deduplicates, makes them searchable.","owner":"terry-li-hm","repoUrl":"https://github.com/terry-li-hm/oghma","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-02-04T22:41:19.000Z","addedAt":"2026-10-21T08:18:06.097Z","logoUrl":"https://avatars.githubusercontent.com/u/12233004?u=3254a5a63c50e71049f47359125eb540f035eee9&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","databases","developer-tools"],"tags":["ai","claude-code","developer-tools","llm","memory","sqlite","ai-memory","coding-assistant"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T03:31:19.442Z","sample":false,"url":"https://conduits.dev/tools/oghma","language":"Python","transports":["stdio"],"install":{"pypi":"oghma"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Oghma\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n\nPersistent memory for AI coding assistants.\n\nOghma hums in the background — watching your coding sessions, extracting technical gotchas and workarounds via LLM, and making them searchable for when you vaguely remember solving something three months ago but forgot how.\n\nIt's a safety net for hard-won discoveries, not a knowledge base or personal wiki. For structured notes and preferences, use your own docs. For \"what was that sqlite-vec trick again?\" — search Oghma.\n\n![demo](demo.gif)\n\n## How it works\n\n```\n┌─────────────┐     ┌───────────┐     ┌──────────┐     ┌────────────┐\n│ Transcripts │────▶│  Extract  │────▶│  Dedup   │────▶│   Store    │\n│ (JSONL)     │     │  (LLM)    │     │ (cosine) │     │ (SQLite)   │\n└─────────────┘     └───────────┘     └──────────┘     └────────────┘\n  Claude Code            │                                    │\n  Codex                  │                                    ▼\n  OpenCode          Categories:                    ┌──────────────────┐\n                    - gotcha                       │  Search (MCP)    │\n                    - learning                     │  keyword / vec / │\n                    - workflow                     │  hybrid (RRF)    │\n                    - preference                   └──────────────────┘\n                    - project_context\n```\n\nA background daemon polls for new/changed transcripts, sends chunks to an LLM for extraction, embeds the results, checks for semantic duplicates, and stores what's genuinely new. Your AI assistant queries this via MCP — so it remembers what you've learned across every session and every tool.\n\n## Features\n\n- **Multi-tool extraction** — Parses transcripts from Claude Code, Codex, OpenCode (and OpenClaw)\n- **LLM-powered filtering** — Configurable model with a tuned prompt that extracts gotchas and workarounds while filtering noise like \"the user prefers Python\"\n- **Hybrid search** — SQLite FTS5 + [sqlite-vec](https://github.com/asg017/sqlite-vec) fused via [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf) with recency boost\n- **Inline dedup** — New memories are checked against existing embeddings before insertion. Duplicates never enter the DB.\n- **[MCP](https://modelcontextprotocol.io/) server** — Plug into Claude Code, Cursor, or any MCP-compatible client\n- **Maintenance CLI** — Semantic dedup, noise purge, staleness pruning, memory promotion\n- **Export** — Markdown or JSON, grouped by category, date, or source\n\n## Quick start\n\n```bash\n# Install\npip install oghma\n\n# Or from source\ngit clone https://github.com/terry-li-hm/oghma.git\ncd oghma\npip install -e \".[dedup]\"\n\n# Set API keys\nexport OPENAI_API_KEY=sk-...          # for embeddings\nexport OPENROUTER_API_KEY=sk-or-...   # if using OpenRouter models for extraction\n\n# Initialize and start\noghma init          # creates ~/.oghma/config.yaml\noghma start         # background daemon\n```\n\nEdit `~/.oghma/config.yaml` to configure your extraction model, tool paths, and embedding settings.\n\n## Integration\n\nTwo ways to connect Oghma to your AI assistant:\n\n### Option A: Claude Code skill (recommended)\n\nZero token overhead — the skill is only loaded when invoked, not on every turn.\n\n```bash\noghma install claude-code\n```\n\nYour assistant will use `oghma search` via CLI when it needs to recall past learnings.\n\n### Option B: MCP server\n\nWorks with any MCP client (Claude Code, Cursor, Windsurf, etc.). Costs ~350 tokens/turn for tool schemas.\n\nAdd to your Claude Code config (`~/.claude.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"oghma\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"oghma\", \"oghma-mcp\"]\n    }\n  }\n}\n```\n\nThis exposes four tools to your AI assistant:\n\n| Tool | Description |\n|------|-------------|\n| `oghma_search` | Search memories (keyword, vector, or hybrid) |\n| `oghma_get` | Fetch a specific memory by ID |\n| `oghma_stats` | Memory counts by category and source |\n| `oghma_categories` | List categories with counts |\n\n## CLI reference\n\n```\noghma init                  Create default config\noghma start [--foreground]  Start the extraction daemon\noghma stop                  Stop the daemon\noghma status [--json]       Daemon status and DB stats\noghma stats                 Memory counts by category/source\n\noghma search <query>        Search memories\n  --mode keyword|vector|hybrid\n  --category, --tool, --status, --limit\n\noghma dedup                 Find and remove semantic duplicates\noghma purge-noise           Remove memories matching noise patterns\noghma prune-stale           Delete memories older than N days\n  --max-age-days 90\n  --source-tool <name>\n\noghma promote <id>          Promote a memory to 'promoted' category\noghma export                Export to markdown or JSON\n  --format, --group-by, --category\n\noghma validate-config       Check config for errors\noghma migrate-embeddings    Backfill embeddings for existing memories\n```\n\nAll destructive commands default to `--dry-run`. Pass `--execute` to apply.\n\n## Configuration\n\n`~/.oghma/config.yaml`:\n\n```yaml\ndaemon:\n  poll_interval: 300          # seconds between checks\n  min_messages: 6             # skip trivial sessions\n\nextraction:\n  model: google/gemini-3-flash-preview   # or gpt-4o-mini, deepseek/deepseek-chat, etc.\n  confidence_threshold: 0.7\n  dedup_threshold: 0.92       # cosine similarity — higher = stricter\n  categories:\n    - learning\n    - preference\n    - project_context\n    - gotcha\n    - workflow\n    - promoted\n\nembedding:\n  provider: openai\n  model: text-embedding-3-small\n  dimensions: 1536\n\ntools:\n  claude_code:\n    enabled: true\n    paths:\n      - ~/.claude/projects/-Users-*/*.jsonl\n  codex:\n    enabled: true\n    paths:\n      - ~/.codex/sessions/**/rollout-*.jsonl\n  opencode:\n    enabled: true\n    paths:\n      - ~/.local/share/opencode/storage/message/ses_*\n```\n\n### Extraction models\n\nOghma supports any OpenAI or OpenRouter model:\n\n| Model | Provider | Quality | Cost |\n|-------|----------|---------|------|\n| google/gemini-3-flash-preview | OpenRouter | Excellent | ~$1.50/M tokens |\n| gpt-4o-mini | OpenAI | Good | ~$0.30/M tokens |\n| deepseek/deepseek-chat-v3-0324 | OpenRouter | Good | ~$0.14/M tokens |\n\n## Search modes\n\n| Mode | Engine | Best for |\n|------|--------|----------|\n| **keyword** | SQLite FTS5 | Exact term matching, fast |\n| **vector** | sqlite-vec (cosine similarity) | Conceptual/semantic search |\n| **hybrid** | RRF fusion of both + recency boost | Best overall relevance |\n\n```bash\noghma search \"async patterns\" --mode hybrid --limit 20\n```\n\n## How memories enter the database\n\nMemories arrive through two paths:\n\n| Path | How | `source_tool` | Best for |\n|------|-----|---------------|----------|\n| **Daemon extraction** | Background daemon processes transcripts via LLM | `claude_code`, `codex`, `opencode` | Catching things you'd forget to note |\n| **Manual addition** | `oghma_add` via MCP or CLI | `manual` | Curated insights you know are valuable |\n\n### Daemon extraction\n\nThe daemon sends conversation chunks to an LLM with a prompt engineered to extract only actionable insights:\n\n**Extracted:** Tool gotchas, bug workarounds, API quirks, architecture decisions, error solutions, workflow patterns.\n\n**Filtered:** Setup facts (\"uses Python 3.12\"), config restatements, assistant narration (\"The AI suggested...\"), trivially obvious observations.\n\nEach memory gets a confidence score and a category. Post-extraction, regex noise patterns catch stragglers. Pre-insertion, embedding similarity catches duplicates. The result: your database grows with genuine insights, not noise.\n\n### Manual addition\n\nYou can add memories directly via the CLI (`oghma add` — coming soon). Use this for curated, high-confidence insights — not as a general notepad. For personal preferences and stable facts, a structured note (e.g., in your knowledge base) is usually a better fit.\n\n## Maintenance\n\n```bash\n# Recommended: run weekly via cron\noghma dedup --threshold 0.92 --execute\noghma purge-noise --execute\n\n# Prune old memories from a retired tool\noghma prune-stale --max-age-days 90 --source-tool openclaw --execute\n\n# Promote a frequently-useful memory\noghma promote 739\n```\n\n## Adding a custom parser\n\nImplement a parser with `can_parse()` and `parse()` methods:\n\n```python\nfrom oghma.parsers import Message\n\nclass MyToolParser:\n    def can_parse(self, file_path: Path) -> bool:\n        return \".mytool\" in str(file_path)\n\n    def parse(self, file_path: Path) -> list[Message]:\n        # Return list of Message(role=\"user\"|\"assistant\", content=\"...\")\n        ...\n```\n\nRegister in `src/oghma/parsers/__init__.py` and add glob patterns to your config.\n\n## Requirements\n\n- Python 3.10+\n- SQLite with FTS5 (included in most distributions)\n- [sqlite-vec](https://github.com/asg017/sqlite-vec) for vector search (optional, recommended)\n- OpenAI API key for embeddings\n- LLM API key for extraction (OpenAI or OpenRouter)\n\n## Environment variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `OPENAI_API_KEY` | Yes | For embeddings (text-embedding-3-small) |\n| `OPENROUTER_API_KEY` | If using OpenRouter | For Gemini, DeepSeek, etc. |\n| `OGHMA_DB_PATH` | No | Override database path |\n| `OGHMA_EXTRACTION_MODEL` | No | Override extraction model |\n| `OGHMA_LOG_LEVEL` | No | DEBUG / INFO / WARNING / ERROR |\n\n## License\n\nMIT\n"}