OSCTX — Universal Memory for AI

You talk to ChatGPT, Claude, and Gemini every day. Every insight, decision, and solution evaporates when you close the tab. OSCTX fixes that.

It runs silently in the background, captures your AI conversations, extracts the knowledge that matters, and makes it searchable in under 500ms — ready to paste into your next conversation as grounded context.

---

How It Works

AI chat tab  →  browser extension  →  POST /ingest  →  LLM extraction  →  sqlite-vec
                                                                               ↓
Raycast / localhost:8765/ui  ←────────────────────────── semantic search ──────┘
                                                                               ↓
Claude Desktop (MCP)  ←──────────────────────── search_knowledge tool ─────────┘

Three components:

1. Capture — Chrome extension monitors ChatGPT, Claude.ai, and Gemini. Trigger manually with Cmd+Shift+S or the popup button. Buffers offline and retries every 60s.
2. Brain — FastAPI daemon on port 8765. Extracts knowledge units via LLM (Anthropic/Gemini/OpenAI/Ollama), embeds with intfloat/e5-small-v2, stores in a single SQLite file with sqlite-vec.
3. Retrieval — Raycast extension, localhost:8765/ui browser UI, or Claude Desktop MCP tools.

---

What Gets Extracted

Each unit is 1–3 self-contained sentences including the reasoning:

• decisions — "Chose UUIDs over auto-increment because the system generates IDs across multiple services without a central coordinator, avoiding tight coupling on a single sequence generator."
• facts — "PostgreSQL JSONB outperforms EAV tables for sparse attributes because JSONB uses a binary format with indexable keys, while EAV requires a JOIN per attribute."
• solutions — "Fixed N+1 with select_related('author__profile') — without it, Django issues one query per object in the loop; select_related collapses them into a single JOIN."
• code_patterns — reusable snippets and idioms
• preferences — your stated tool/language/library preferences
• references — papers, docs, links worth keeping

Low-confidence units (< 0.7) are discarded. Near-duplicates (cosine similarity > 0.97) are skipped.

---

Quick Setup (fresh clone)

1 — Python environment

git clone https://github.com/you/osctx
cd osctx
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[gemini]"    # swap 'gemini' for 'openai' or 'anthropic'

2 — Configure your LLM key

osctx config --set extraction_backend=gemini
osctx config --set gemini_api_key=YOUR_KEY
# or: osctx config --set extraction_backend=anthropic
#     osctx config --set anthropic_api_key=YOUR_KEY

3 — Start the daemon

# One-time, in a terminal (keep it running):
.venv/bin/uvicorn osctx.daemon.main:app --host 127.0.0.1 --port 8765

# Or auto-start on login (macOS):
osctx install

# Check health:
osctx logs          # status + live log tail
osctx doctor        # dependency check

4 — Browser extension (Chrome)

1. Open Chrome → navigate to chrome://extensions
2. Toggle Developer mode on (top-right switch)
3. Click Load unpacked → select the extension/ folder from this repo
4. The OSCTX icon appears in your toolbar. Click Pin to keep it visible.

Usage:

• Navigate to any ChatGPT, Claude.ai, or Gemini conversation
• Click the extension icon → click Capture to send the conversation to the daemon
• Or press Cmd+Shift+S anywhere on the page

The daemon must be running (step 3) to receive captures. If offline, captures are buffered in the extension and retried every 60s.

5 — Raycast extension (optional)

cd raycast-extension
npm install
npm run build

Open Raycast → Extensions → + Import Extension → select raycast-extension/. Search with Search Memory.

6 — Claude Desktop MCP (optional)

pip install -e ".[mcp]"
osctx mcp install       # writes Claude Desktop config
# Quit and reopen Claude Desktop

---

Import Existing History

ChatGPT: Settings → Data Controls → Export Data → download conversations.json

osctx import ~/Downloads/conversations.json --source chatgpt

Gemini: takeout.google.com → select "Gemini Apps Activity" → download

osctx import ~/Downloads/Takeout/Gemini/Gemini\ Apps\ Activity.json --source gemini

Monitor extraction progress:

osctx logs

---

Search & Retrieval

Browser UI — open http://localhost:8765/ui:

• Search tab: semantic + hybrid search with category/source filters
• Browse tab: all units grouped by category (Decisions, Solutions, Facts…)
• Recent tab: last 50 units by capture time — first thing to check after a capture
• Click any card to copy as <context> XML. Shift+click or Cmd+click to multi-select.
• Hover any card to reveal ✕ — deletes the unit permanently.

CLI:

osctx search "postgres indexing strategy"

Raycast — Search Memory, then:

• Enter → copy top result as context
• Cmd+D → toggle select, build a batch
• Cmd+Enter when items selected → copy all selected

Paste format:

<context source="Chatgpt" date="2025-11-03" topic="database, postgresql">
## Conversation Summary
Optimized a SaaS analytics backend — explored indexing strategies for soft-delete patterns.

## Matched Knowledge
Chose partial indexes (WHERE deleted_at IS NULL) over full btree indexes because query
time drops 90% on tables where < 5% of rows are deleted, avoiding index bloat.
</context>

---

Claude Desktop (MCP)

After osctx mcp install and restarting Claude Desktop, four tools are available:

Tool	When Claude uses it
search_knowledge	Automatically when you ask about past decisions, projects, preferences
get_by_topic	"Show me everything about postgres"
save_insight	"Remember this", "Note that", mid-conversation facts
ingest_conversation	"Save this chat to memory", "Extract knowledge from this conversation"

Example prompts:

"What do I know about authentication strategies?" "Save this conversation to memory" "Do I have any notes on React performance?"

---

Monitoring

osctx logs             # status + live daemon log (Ctrl+C to stop)
osctx status           # snapshot stats
osctx status --watch   # refresh every 3s
curl http://localhost:8765/status | python3 -m json.tool

MCP server logs (Claude Desktop):

tail -f ~/Library/Logs/Claude/mcp-server-osctx.log

---

Storage

Everything lives in ~/.osctx/:

~/.osctx/
├── memory.db       # SQLite + sqlite-vec (vectors + knowledge units)
├── config.json     # API keys and settings
├── queue.json      # Persisted extraction queue (survives crashes)
├── daemon.log      # Daemon logs
└── backups/        # Manual backups

No cloud. No separate vector database. No Redis. One file.

---

Configuration

osctx config --show
osctx config --set extraction_backend=gemini
osctx config --set search_result_limit=10

Full config schema:

{
  "extraction_backend": "anthropic",
  "anthropic_api_key": "",
  "gemini_api_key": "",
  "gemini_model": "gemini-flash-latest",
  "openai_api_key": "",
  "ollama_model": "llama3.2:3b",
  "ollama_base_url": "http://localhost:11434",
  "extraction_on_battery": false,
  "dedup_threshold_hard": 0.97,
  "dedup_threshold_soft": 0.90,
  "search_result_limit": 5,
  "search_score_threshold": 0.5,
  "auto_start": true,
  "backup_enabled": true
}

---

Development

source .venv/bin/activate
.venv/bin/pytest          # all tests (no API calls — all mocked)
osctx doctor              # check environment

Key docs:

• docs/INTERFACES.md — public API of every module
• docs/STATUS.md — what's built, what's not, known issues
• docs/CONSTRAINTS.md — hard rules (import graph, test rules)
• docs/DECISIONS.md — tech stack decisions, locked
• docs/NEXT.md — prioritized next tasks

Note for Homebrew Python users: sqlite-vec requires conn.enable_load_extension(True) before loading. Already handled in database.py — mention if you see not authorized errors.

---

Why Not Just Use [Tool X]?

• Mem0 / mem.ai — cloud, opinionated, not yours
• Obsidian + plugins — manual, copy-paste, no auto-capture
• Notion AI — requires you to manually save to Notion first
• Browser history — can't search by meaning, no extraction

OSCTX is local-first, works across all AI tools, extracts semantic knowledge (not raw transcripts), and takes zero manual effort after setup.