ogham-mcp 0.3.0__tar.gz

ogham_mcp-0.3.0/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "ogham"
+  ],
+  "permissions": {
+    "allow": [
+      "mcp__ogham__health_check"
+    ]
+  }
+}

ogham_mcp-0.3.0/.dockerignore

@@ -0,0 +1,13 @@
+.venv/
+.env
+.git/
+.ruff_cache/
+__pycache__/
+*.pyc
+*.pyo
+tests/
+docs/
+*.md
+!README.md
+.pytest_cache/
+starter.md

ogham_mcp-0.3.0/.env.example

@@ -0,0 +1,39 @@
+# Required
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_KEY=your-service-role-key
+
+# Embedding provider: "ollama" (default), "openai", "mistral", or "voyage"
+EMBEDDING_PROVIDER=ollama
+
+# Embedding dimensions — auto-set per provider if omitted:
+#   ollama: 512, openai: 1024, mistral: 1024, voyage: 1024
+# Override only if using a non-default model with different dimensions.
+# EMBEDDING_DIM=512
+
+# Ollama settings (default)
+# Use localhost for native install, host.docker.internal for Docker
+OLLAMA_URL=http://localhost:11434
+OLLAMA_EMBED_MODEL=embeddinggemma
+
+# OpenAI settings (if EMBEDDING_PROVIDER=openai)
+# OPENAI_API_KEY=sk-...
+
+# Mistral settings (if EMBEDDING_PROVIDER=mistral)
+# MISTRAL_API_KEY=your-mistral-key
+# MISTRAL_EMBED_MODEL=mistral-embed
+
+# Voyage settings (if EMBEDDING_PROVIDER=voyage)
+# VOYAGE_API_KEY=your-voyage-key
+# VOYAGE_EMBED_MODEL=voyage-4-lite
+
+# Search defaults
+# Threshold depends on embedding provider — each clusters vectors differently:
+#   Ollama (embeddinggemma): 0.7 — tight clustering, scores run 0.8-0.9
+#   Mistral (mistral-embed): 0.6 — tight clustering, similar to Ollama
+#   Voyage (voyage-4-lite): 0.45 — moderate spread
+#   OpenAI (text-embedding-3-small): 0.35 — widest spread, scores run 0.5-0.6
+DEFAULT_MATCH_THRESHOLD=0.7
+DEFAULT_MATCH_COUNT=10
+
+# Memory profile (Severance-style partitioning: "lumon", "personal", "projects", etc)
+DEFAULT_PROFILE=default

ogham_mcp-0.3.0/.github/workflows/docker-build.yml

@@ -0,0 +1,62 @@
+# Multi-platform Docker build for linux/amd64 + linux/arm64.
+#
+# TODO(public launch): Restrict GHCR push to tags only. Currently pushes on
+# every main commit for testing during private development. Change the Login
+# and Build steps back to: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+
+name: Docker Build
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        if: github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha,prefix=,format=short
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name == 'push' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

ogham_mcp-0.3.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Environment
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# MCP config (local per-machine)
+.mcp*.json
+
+# UV
+
+# Docker
+.worktrees/

ogham_mcp-0.3.0/.python-version

@@ -0,0 +1 @@
+3.13

ogham_mcp-0.3.0/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.3.0] - 2026-03-07 — Relationship Graph
+
+### Added
+- **Relationship graph** — `memory_relationships` table with typed, weighted edges (`similar`, `supports`, `contradicts`, `related`, `follows`, `derived_from`). Built entirely in PostgreSQL with recursive CTEs — no separate graph database or LLM needed
+- **Auto-linking** — new memories are automatically linked to similar existing memories on store via HNSW vector search (threshold 0.85, max 5 links). One database round-trip, no LLM in the write path
+- `explore_knowledge` tool — hybrid search seeds + recursive CTE graph traversal. Finds memories by meaning, then expands via relationship edges to pull in connected context
+- `find_related` tool — traverses the graph outward from a known memory ID for impact analysis
+- `store_decision` tool — stores architectural decisions with structured metadata (rationale, alternatives) and `supports` edges to related memories
+- `link_unlinked` tool — backfills auto-links for memories that predate the relationship graph. Configurable threshold and batch size
+- `store_memory` gains `auto_link` parameter (default `True`) and returns `links_created` count
+- Stress test script (`tests/bench_stress.py`) — imports 1000+ memories, verifies dedup, backfills auto-links, benchmarks graph operations at scale
+- Benchmark coverage for auto-link, explore graph, and get related operations
+
+### Fixed
+- `link_unlinked_memories` RPC infinite loop — `PERFORM` discarded return value, causing memories with no similar neighbors to be reprocessed indefinitely. Fixed with `SELECT INTO` and conditional increment
+
+### Schema Changes
+- Run `sql/migrations/008_memory_relationships.sql`, `009_graph_explorer.sql`, `010_impact_analysis.sql` in order, or re-run `sql/schema.sql` for fresh installs
+- New table: `memory_relationships` (source_id, target_id, relationship, strength, metadata)
+- New enum: `relationship_type`
+- New RPCs: `auto_link_memory`, `link_unlinked_memories`, `explore_memory_graph`, `get_related_memories`
+
+## [0.2.1] - 2026-03-05 — Supabase Best Practices
+
+### Changed
+- **RLS hardened** — `FORCE ROW LEVEL SECURITY` on `memories` and `profile_settings`, deny `anon` role access by default
+- **Composite index** — replaced separate `profile` and `created_at` indexes with `(profile, created_at DESC)` for faster filtered queries
+- **Keyset pagination** — `get_all_memories_full` and `get_all_memories_content` now use cursor-based pagination instead of OFFSET
+- **Batch re-embed** — `re_embed_all` uses new `batch_update_embeddings` RPC (batches of 50) instead of individual updates
+
+### Added
+- `batch_update_embeddings` RPC function for efficient bulk embedding updates
+- `CHECK` constraint on `profile_settings.ttl_days` (`>= 1` or NULL)
+- RLS policies on `profile_settings` table
+
+### Schema Changes
+- Run `sql/migrate_best_practices.sql` to upgrade existing installs
+
+## [0.2.0] - 2026-03-05 — Quality of Life Release
+
+### Added
+- **LRU embedding cache** with configurable max size (`EMBEDDING_CACHE_MAX_SIZE`, default 1000) and `get_cache_stats()` tool for monitoring
+- **Memory expiration** with profile-bound TTLs — `set_profile_ttl()` sets days until memories expire, `cleanup_expired()` permanently removes them
+- **Profile settings table** (`profile_settings`) for storing per-profile TTL configuration
+- **MCP prompts** — `summarize-recent`, `find-decisions`, `profile-overview`, `cleanup-check`
+- **HTTP health endpoint** — optional `GET /health` on configurable port (`ENABLE_HTTP_HEALTH`, `HEALTH_PORT`)
+- **CLI tool** — `ogham` command with subcommands: serve, health, profiles, stats, search, list, cleanup, export, import, openapi
+- **OpenAPI spec generation** — `ogham openapi` generates `docs/openapi.json` from MCP tool definitions
+- **Export/import** — `export_profile()` exports as JSON or Markdown, `import_memories_tool()` imports with dedup
+
+### Changed
+- `match_memories`, `get_profile_counts`, `get_memory_stats_sql` RPCs now filter expired memories
+- `list_recent_memories` now filters expired memories and returns `expires_at`
+- `store_memory` now computes `expires_at` from profile TTL when set
+- Entry point changed: `ogham` now runs CLI (use `ogham serve` for MCP server, or `ogham-serve`)
+- Embedding cache changed from unbounded dict to OrderedDict-based LRU
+
+### Schema Changes
+- New table: `profile_settings` (profile, ttl_days, created_at, updated_at)
+- New column: `memories.expires_at` (timestamptz, nullable)
+- New RPCs: `cleanup_expired_memories()`, `count_expired_memories()`
+- Run `sql/migrate_expiration.sql` to upgrade existing installs
+
+## [0.1.1] - 2026-03-05
+
+### Added
+- `health_check` tool for diagnosing connection issues
+- Startup validation -- exits with clear errors if Supabase or Ollama aren't reachable
+- Retry with exponential backoff on transient failures (embedding: 3 attempts, DB reads: 2)
+- Input validation for content, threshold, and limit parameters
+- Embedding cache (SHA256-keyed) to skip re-embedding identical content
+- SQL aggregation functions (`get_profile_counts`, `get_memory_stats_sql`) replacing Python-side counting
+- Progress reporting for `re_embed_all`
+- Tool execution timing logged to stderr
+
+### Fixed
+- `update_memory` / `store_memory` crash when Supabase returns empty results
+- `delete_memory` / `update_memory` could affect memories in other profiles
+
+### Changed
+- `get_stats()` returns `total` instead of `total_memories`
+- OpenAI is now an optional dependency (`uv sync --extra openai`)
+- New RPC functions required -- re-run `sql/schema.sql`
+
+## [0.1.0] - 2026-03-05
+
+### Added
+- Initial release
+- MCP server with stdio transport
+- Supabase PostgreSQL + pgvector backend
+- Ollama and OpenAI embedding providers
+- Memory profiles (Severance-style partitioning)
+- Semantic search with cosine similarity
+- Tag and source filtering
+- Docker and native (UV) deployment options
+- Support for Claude Desktop, Cursor, Claude Code, VS Code, Codex, Windsurf

ogham_mcp-0.3.0/Dockerfile

@@ -0,0 +1,27 @@
+# --- Stage 1: Build ---
+FROM python:3.13-slim AS builder
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock .python-version ./
+RUN uv sync --frozen --no-dev --no-editable --no-install-project --extra all
+
+COPY src/ src/
+RUN uv sync --frozen --no-dev --no-editable --extra all
+
+# --- Stage 2: Runtime ---
+FROM python:3.13-slim
+
+WORKDIR /app
+
+COPY --from=builder /app/.venv /app/.venv
+COPY src/ ./src/
+
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV OLLAMA_URL=http://host.docker.internal:11434
+
+ENTRYPOINT ["ogham"]

ogham_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Burns
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ogham_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: ogham-mcp
+Version: 0.3.0
+Summary: Shared memory MCP server — persistent, searchable, cross-client
+Project-URL: Homepage, https://ogham-mcp.dev
+Project-URL: Repository, https://github.com/ogham-mcp/ogham-mcp
+Project-URL: Documentation, https://ogham-mcp.dev
+Author: Kevin Burns
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,embeddings,mcp,memory,pgvector,supabase
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.13
+Requires-Dist: fastmcp>=2.14
+Requires-Dist: ollama>=0.4
+Requires-Dist: openai>=1.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: supabase>=2.0
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: mistralai>=1.0; extra == 'all'
+Requires-Dist: psycopg-pool>=3.1; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
+Requires-Dist: voyageai>=0.3; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: mistral
+Requires-Dist: mistralai>=1.0; extra == 'mistral'
+Provides-Extra: postgres
+Requires-Dist: psycopg-pool>=3.1; extra == 'postgres'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: voyage
+Requires-Dist: voyageai>=0.3; extra == 'voyage'
+Description-Content-Type: text/markdown
+
+# Ogham MCP
+
+*Ogham* (pronounced "OH-um") -- persistent, searchable shared memory for AI coding agents. Works across clients.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Docker](https://img.shields.io/badge/Docker-ghcr.io%2Fogham--mcp%2Fogham--mcp-blue)](https://github.com/ogham-mcp/ogham-mcp/pkgs/container/ogham-mcp)
+
+## The problem
+
+AI coding agents forget everything between sessions. Switch from Claude Code to Cursor to Kiro to OpenCode and context is lost. Decisions, gotchas, architectural patterns -- gone. You end up repeating yourself, re-explaining your codebase, re-debugging the same issues.
+
+Ogham gives your agents a shared memory that persists across sessions and clients.
+
+## Quick start
+
+### 1. Set up your database
+
+**Supabase** (free tier works): create a project at [supabase.com](https://supabase.com), then run `sql/schema.sql` in the SQL editor.
+
+**Postgres** ([Neon](https://neon.tech), self-hosted, etc.): run `sql/schema_postgres.sql` against your database. Needs PostgreSQL 15+ with pgvector.
+
+### 2. Install
+
+```bash
+# From PyPI (recommended)
+claude mcp add ogham -- uvx ogham-mcp
+
+# Before PyPI publish, install from GitHub
+uvx --from git+https://github.com/ogham-mcp/ogham-mcp.git ogham init
+claude mcp add ogham -- uvx --from git+https://github.com/ogham-mcp/ogham-mcp.git ogham-serve
+```
+
+The `ogham init` wizard walks you through database setup, embedding provider, and writes MCP client configs. Run it before adding the server to your client.
+
+### 3. Configure
+
+```bash
+# Supabase
+export SUPABASE_URL=https://your-project.supabase.co
+export SUPABASE_KEY=your-service-role-key
+export EMBEDDING_PROVIDER=openai  # or ollama, mistral, voyage
+export OPENAI_API_KEY=sk-...      # for your chosen provider
+
+# Or Postgres (Neon, self-hosted)
+export DATABASE_BACKEND=postgres
+export DATABASE_URL=postgresql://user:pass@host/db
+export EMBEDDING_PROVIDER=openai
+export OPENAI_API_KEY=sk-...
+```
+
+Or skip the manual setup and run the interactive wizard:
+
+```bash
+ogham init
+```
+
+It walks you through database connection, embedding provider, schema migration, and writes MCP client configs for Claude Code, Cursor, VS Code, and others.
+
+### 4. Use it
+
+Tell your agent to remember something, then ask about it later -- from the same client or a different one. It works because they all hit the same database.
+
+## Installation methods
+
+| Method | Command | When to use |
+|--------|---------|-------------|
+| **uvx** (recommended) | `uvx ogham-mcp` | PyPI is published, quick setup |
+| **uvx from GitHub** | `uvx --from git+https://github.com/ogham-mcp/ogham-mcp.git ogham-serve` | Before PyPI, testing from source |
+| **Docker** | `docker pull ghcr.io/ogham-mcp/ogham-mcp` | Isolation, self-hosted |
+| **Git clone** | `git clone` + `uv sync` | Development, contributions |
+
+### Claude Code
+
+```bash
+# From PyPI
+claude mcp add ogham -- uvx ogham-mcp
+
+# From GitHub (before PyPI) -- run ogham init first to configure your database and provider
+claude mcp add ogham -- uvx --from git+https://github.com/ogham-mcp/ogham-mcp.git ogham-serve
+```
+
+### OpenCode
+
+Add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "mcp": {
+    "ogham": {
+      "type": "local",
+      "command": ["uvx", "ogham-mcp"],
+      "environment": {
+        "SUPABASE_URL": "https://your-project.supabase.co",
+        "SUPABASE_KEY": "{env:SUPABASE_KEY}",
+        "EMBEDDING_PROVIDER": "openai",
+        "OPENAI_API_KEY": "{env:OPENAI_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Docker
+
+```bash
+docker run --rm \
+  -e SUPABASE_URL=https://your-project.supabase.co \
+  -e SUPABASE_KEY=your-key \
+  -e EMBEDDING_PROVIDER=openai \
+  -e OPENAI_API_KEY=sk-... \
+  ghcr.io/ogham-mcp/ogham-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/ogham-mcp/ogham-mcp.git
+cd ogham-mcp
+uv sync
+uv run ogham --help
+```
+
+## Entry points
+
+Ogham has two entry points:
+
+- **`ogham`** -- the CLI. Use this for `ogham init`, `ogham health`, `ogham search`, and other commands you run yourself. Running `ogham` with no arguments starts the MCP server.
+- **`ogham-serve`** -- starts the MCP server directly. This is what MCP clients should call. When you run `uvx ogham-mcp`, it invokes `ogham-serve`.
+
+## CLI
+
+```bash
+ogham init                      # Interactive setup wizard
+ogham health                    # Check database + embedding provider
+ogham search "query"            # Search memories from the terminal
+ogham store "some fact"         # Store a memory
+ogham list                      # List recent memories
+ogham profiles                  # List profiles and counts
+ogham stats                     # Profile statistics
+ogham export -o backup.json     # Export memories
+ogham import backup.json        # Import memories
+ogham cleanup                   # Remove expired memories
+ogham serve                     # Start MCP server (default)
+ogham openapi                   # Generate OpenAPI spec
+```
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DATABASE_BACKEND` | No | `supabase` | `supabase` or `postgres` |
+| `SUPABASE_URL` | If supabase | -- | Your Supabase project URL |
+| `SUPABASE_KEY` | If supabase | -- | Supabase secret key (service_role) |
+| `DATABASE_URL` | If postgres | -- | PostgreSQL connection string |
+| `EMBEDDING_PROVIDER` | No | `ollama` | `ollama`, `openai`, `mistral`, or `voyage` |
+| `EMBEDDING_DIM` | No | `512` | Vector dimensions -- must match your schema (see below) |
+| `OPENAI_API_KEY` | If openai | -- | OpenAI API key |
+| `MISTRAL_API_KEY` | If mistral | -- | Mistral API key |
+| `VOYAGE_API_KEY` | If voyage | -- | Voyage AI API key |
+| `OLLAMA_URL` | No | `http://localhost:11434` | Ollama server URL |
+| `OLLAMA_EMBED_MODEL` | No | `embeddinggemma` | Ollama embedding model |
+| `MISTRAL_EMBED_MODEL` | No | `mistral-embed` | Mistral embedding model |
+| `VOYAGE_EMBED_MODEL` | No | `voyage-4-lite` | Voyage embedding model |
+| `DEFAULT_MATCH_THRESHOLD` | No | `0.7` | Similarity threshold (see below) |
+| `DEFAULT_MATCH_COUNT` | No | `10` | Max results per search |
+| `DEFAULT_PROFILE` | No | `default` | Memory profile name |
+
+### Embedding providers
+
+| Provider | Default dimensions | Recommended threshold | Notes |
+|----------|-------------------|----------------------|-------|
+| OpenAI | 512 (schema default) | 0.35 | Set `EMBEDDING_DIM=512` explicitly -- OpenAI defaults to 1024 |
+| Ollama | 512 | 0.70 | Tight clustering, scores run 0.8-0.9 |
+| Mistral | 1024 | 0.60 | Fixed 1024 dims, can't truncate. Schema must be `vector(1024)` |
+| Voyage | 512 (schema default) | 0.45 | Moderate spread |
+
+`EMBEDDING_DIM` must match the `vector(N)` column in your database schema. The default schema uses `vector(512)`. If you use Mistral, you need to alter the column to `vector(1024)` before storing anything.
+
+Each provider clusters vectors differently, so the similarity threshold matters. Start with the recommended value and adjust based on your results.
+
+## MCP tools
+
+### Memory operations
+
+| Tool | Description | Key parameters |
+|------|-------------|----------------|
+| `store_memory` | Store a new memory with embedding | `content` (required), `source`, `tags[]`, `auto_link` |
+| `store_decision` | Store an architectural decision | `decision`, `reasoning`, `alternatives[]`, `tags[]` |
+| `update_memory` | Update content of existing memory | `memory_id`, `content`, `tags[]` |
+| `delete_memory` | Delete a memory by ID | `memory_id` |
+| `reinforce_memory` | Increase confidence score | `memory_id` |
+| `contradict_memory` | Decrease confidence score | `memory_id` |
+
+### Search
+
+| Tool | Description | Key parameters |
+|------|-------------|----------------|
+| `hybrid_search` | Combined semantic + full-text search (RRF) | `query`, `limit`, `threshold`, `tags[]` |
+| `list_recent` | List recent memories | `limit`, `profile` |
+| `find_related` | Find memories related to a given one | `memory_id`, `limit` |
+
+### Knowledge graph
+
+| Tool | Description | Key parameters |
+|------|-------------|----------------|
+| `link_unlinked` | Auto-link memories by embedding similarity | `threshold`, `limit` |
+| `explore_knowledge` | Traverse the knowledge graph | `memory_id`, `depth`, `direction` |
+
+### Profiles
+
+| Tool | Description | Key parameters |
+|------|-------------|----------------|
+| `switch_profile` | Switch active memory profile | `profile` |
+| `current_profile` | Show active profile | -- |
+| `list_profiles` | List all profiles with counts | -- |
+| `set_profile_ttl` | Set auto-expiry for a profile | `profile`, `ttl_days` |
+
+### Import / export
+
+| Tool | Description | Key parameters |
+|------|-------------|----------------|
+| `export_profile` | Export all memories in active profile | `format` (`json` or `markdown`) |
+| `import_memories_tool` | Import memories with deduplication | `data`, `dedup_threshold` |
+
+### Maintenance
+
+| Tool | Description | Key parameters |
+|------|-------------|----------------|
+| `re_embed_all` | Re-embed all memories (after switching providers) | -- |
+| `cleanup_expired` | Remove expired memories (TTL) | -- |
+| `health_check` | Check database and embedding connectivity | -- |
+| `get_stats` | Memory counts, profiles, activity | -- |
+| `get_cache_stats` | Embedding cache hit rates | -- |
+
+## Skills
+
+Ogham ships with three workflow skills in `skills/` that teach AI assistants how to orchestrate the MCP tools above. Install them in Claude Code, Cursor, or any client that supports skills.
+
+| Skill | Triggers on | What it does |
+|-------|-------------|-------------|
+| `ogham-research` | "remember this", "store this finding", "save what we learned" | Checks for duplicates via hybrid_search before storing. Auto-tags with a consistent scheme (`type:decision`, `type:gotcha`, etc.). Uses `store_decision` for architectural choices. |
+| `ogham-recall` | "what do I know about X", "find related", "context for this project" | Chains hybrid_search, find_related, and explore_knowledge to surface connections. Bootstraps session context at project start. |
+| `ogham-maintain` | "memory stats", "clean up my memory", "export my brain" | Runs health_check, get_stats, cleanup_expired, re_embed_all, link_unlinked. Warns before irreversible operations. |
+
+The skills orchestrate existing MCP tools -- they don't replace them. The MCP server must be connected for skills to work.
+
+To install (Claude Code):
+
+```bash
+cp -r skills/ogham-research skills/ogham-recall skills/ogham-maintain ~/.claude/skills/
+```
+
+## Database setup
+
+Ogham works with Supabase or vanilla PostgreSQL. Run the schema file that matches your setup:
+
+| File | Use case |
+|------|----------|
+| `sql/schema.sql` | [Supabase](https://supabase.com) Cloud |
+| `sql/schema_selfhost_supabase.sql` | Self-hosted Supabase with RLS |
+| `sql/schema_postgres.sql` | Vanilla PostgreSQL / [Neon](https://neon.tech) (no RLS) |
+
+Supabase and Neon both include pgvector out of the box -- no extra setup needed. If you're self-hosting Postgres, you need PostgreSQL 15+ with the [pgvector](https://github.com/pgvector/pgvector) extension installed. We develop and test against PostgreSQL 17.
+
+For Postgres, set `DATABASE_BACKEND=postgres` and `DATABASE_URL=postgresql://...` in your environment.
+
+## Architecture
+
+Ogham runs as an MCP server over stdio. Your AI client connects to it like any other MCP tool.
+
+```
+AI Client (Claude Code, Cursor, Kiro, OpenCode, ...)
+    |
+    | stdio (MCP protocol)
+    |
+Ogham MCP Server
+    |
+    | HTTPS (Supabase REST API) or direct connection (Postgres)
+    |
+PostgreSQL + pgvector
+```
+
+Memories are stored as rows with vector embeddings. Search combines pgvector cosine similarity with PostgreSQL full-text search using Reciprocal Rank Fusion (RRF).
+
+The knowledge graph uses a `memory_relationships` table with recursive CTEs for traversal -- no separate graph database.
+
+## Documentation
+
+Full docs and integration guides at [ogham-mcp.dev](https://ogham-mcp.dev).
+
+## Credits
+
+Inspired by [Nate B Jones](https://www.youtube.com/watch?v=2JiMmye2ezg) and his work on persistent AI memory.
+
+Named after [Ogham](https://en.wikipedia.org/wiki/Ogham), the ancient Irish alphabet carved into stone -- the original persistent memory.
+
+## License
+
+MIT