{"id":44917262,"url":"https://github.com/hurttlocker/cortex","last_synced_at":"2026-03-05T03:03:35.800Z","repository":{"id":338921339,"uuid":"1159699868","full_name":"hurttlocker/cortex","owner":"hurttlocker","description":"Import-first, zero-dependency, observable memory layer for AI agents","archived":false,"fork":false,"pushed_at":"2026-02-26T06:08:38.000Z","size":2642,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-26T08:22:34.710Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hurttlocker.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-17T03:45:17.000Z","updated_at":"2026-02-26T06:08:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hurttlocker/cortex","commit_stats":null,"previous_names":["hurttlocker/cortex"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/hurttlocker/cortex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hurttlocker%2Fcortex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hurttlocker%2Fcortex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hurttlocker%2Fcortex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hurttlocker%2Fcortex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hurttlocker","download_url":"https://codeload.github.com/hurttlocker/cortex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hurttlocker%2Fcortex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30107646,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T01:39:18.192Z","status":"online","status_checked_at":"2026-03-05T02:00:06.710Z","response_time":93,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-18T02:15:19.252Z","updated_at":"2026-03-05T03:03:35.786Z","avatar_url":"https://github.com/hurttlocker.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/cortex-logo-redpink-transparent.png\" alt=\"Cortex\" width=\"120\" height=\"120\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eCortex\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eMemory that forgets — so your agent doesn't have to remember everything forever.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/hurttlocker/cortex/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/hurttlocker/cortex/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/hurttlocker/cortex/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/hurttlocker/cortex?include_prereleases\u0026label=release\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/hurttlocker/cortex/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nImport your existing files. Search with hybrid or RRF retrieval. Watch facts fade and reinforce what matters.\n\nNo API keys. No Docker. No config. A single 12MB binary and a SQLite file.\n\n## Install (pick one)\n\n```bash\n# Homebrew (macOS)\nbrew install hurttlocker/cortex/cortex-memory\n\n# MCP server (any platform — no install needed)\nnpx @cortex-ai/mcp\n\n# Binary (macOS Apple Silicon)\ncurl -sSL https://github.com/hurttlocker/cortex/releases/latest/download/cortex-darwin-arm64.tar.gz | tar xz\nsudo mv cortex /usr/local/bin/\n\n# Go\ngo install github.com/hurttlocker/cortex/cmd/cortex@latest\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eOther platforms\u003c/summary\u003e\n\n| Platform | Command |\n|----------|---------|\n| macOS Intel | `curl -sSL .../cortex-darwin-amd64.tar.gz \\| tar xz \u0026\u0026 sudo mv cortex /usr/local/bin/` |\n| Linux x86_64 | `curl -sSL .../cortex-linux-amd64.tar.gz \\| tar xz \u0026\u0026 sudo mv cortex /usr/local/bin/` |\n| Linux ARM64 | `curl -sSL .../cortex-linux-arm64.tar.gz \\| tar xz \u0026\u0026 sudo mv cortex /usr/local/bin/` |\n| Windows | Download from [Releases](https://github.com/hurttlocker/cortex/releases/latest) |\n\nReplace `...` with `https://github.com/hurttlocker/cortex/releases/latest/download`\n\u003c/details\u003e\n\n## Quick start (60 seconds)\n\n```bash\n# 1. Setup (auto-detects your LLM keys + Ollama)\ncortex init\n\n# 2. Import your files\ncortex import ~/notes/ --recursive --extract\n\n# 3. Search your knowledge\ncortex search \"what did I decide about the API design\"\n\n# 4. Connect to your agent (Claude Code, Cursor, Windsurf, etc.)\nclaude mcp add cortex -- cortex mcp\n```\n\nThat's it. Your agent now has persistent memory with 17 MCP tools.\n\n\u003e **No LLM keys?** Cortex works fully offline — import, search (BM25), and MCP all work without any API keys. Add an LLM provider later for enrichment, classification, and semantic search.\n\n### Verify your setup\n\n```bash\ncortex doctor    # Checks DB, config, embeddings, connectors, version\n```\n\n### Next steps\n\n```bash\n# Connect external sources — GitHub, Gmail, Slack, Calendar, Drive\ncortex connect add github --config '{\"token\": \"ghp_...\", \"repos\": [\"owner/repo\"]}'\ncortex connect sync --all --extract   # Import + extract facts in one step\n\n# Add semantic search (requires Ollama)\nollama pull nomic-embed-text\ncortex embed ollama/nomic-embed-text\ncortex search \"API design\" --mode hybrid   # BM25 + semantic\n\n# Explore your knowledge graph\ncortex graph --serve --port 8090      # Opens interactive 2D explorer\n\n# Check health of your knowledge base\ncortex stale --days 30                # What's fading?\ncortex conflicts                      # Any contradictions?\ncortex stats                          # Memory/fact/source counts\n\n# Multi-agent? Scope facts by agent\ncortex import notes.md --agent mister --extract\ncortex search \"config\" --agent mister\n```\n\nSee [docs/connectors.md](docs/connectors.md) for full connector setup.\n\n### Shell completions\n\n```bash\n# Bash\ncortex completion bash \u003e /etc/bash_completion.d/cortex\n\n# Zsh (add to your .zshrc)\ncortex completion zsh \u003e \"${fpath[1]}/_cortex\"\n\n# Fish\ncortex completion fish \u003e ~/.config/fish/completions/cortex.fish\n```\n\n## Why Cortex\n\n**Memory that fades like yours.** Facts decay over time using [Ebbinghaus curves](https://en.wikipedia.org/wiki/Forgetting_curve) — identity facts last years, temporal facts fade in days. When you search, stale facts rank lower. Reinforce what matters; let the rest go.\n\n**Import-first.** Start with the files you already have — `MEMORY.md`, JSON configs, YAML, CSV, conversation logs. Every other tool says \"start fresh.\" Cortex says \"bring everything.\"\n\n**Zero dependencies.** No API keys required, no Docker, no database server. A single Go binary + SQLite. LLM enrichment is optional — dramatically improves fact quality when enabled, but rules work fine offline.\n\n**Observable.** `cortex stats` shows what your agent knows. `cortex stale` shows what's fading. `cortex conflicts` finds contradictions. `cortex alerts` notifies you proactively.\n\n## How it works\n\n```\nYour files ──→ Import ──→ Fact extraction ──→ SQLite + FTS5\n                                                   │\n                              ┌─────────┬──────────┼──────────┐\n                              ▼         ▼          ▼          ▼\n                           Search    Observe    Graph      MCP Server\n                          (hybrid)  (stats,    (2D         (17 tools,\n                                    stale,     explorer)    any agent)\n                                    conflicts)\n```\n\n**Search:** BM25 keyword + optional semantic embeddings, fused with Weighted Score Fusion (default hybrid) or Reciprocal Rank Fusion (`--mode rrf`).\n**Facts:** Extracted as subject-predicate-object triples with type-aware decay rates.\n**Graph:** Interactive 2D knowledge graph explorer with cluster visualization.\n**Connect:** Sync from GitHub, Gmail, Calendar, Drive, Slack, Discord, Telegram, Notion — extract facts on import.\n\n## Feature highlights\n\n| Feature | What it does |\n|---------|-------------|\n| **Hybrid + RRF search** | BM25 + semantic with weighted score fusion (hybrid) or rank fusion (`--mode rrf`). |\n| **Ebbinghaus decay** | 7 decay rates by fact type. Identity lasts 693 days, temporal fades in 7. |\n| **Fact extraction** | Rule-based + LLM enrichment (v0.9.0). Finds entities, decisions, preferences, relationships. Auto-classifies facts. |\n| **Conflict detection** | Same subject + predicate, different object → alert. Real-time on ingest. |\n| **Import filters** | `--ext md,txt` / `--exclude-ext log,tmp` — control exactly what gets imported. |\n| **Auto-infer** | `--extract` on import runs fact extraction + edge inference automatically. |\n| **Knowledge graph** | `cortex graph --serve` — interactive 2D cluster explorer in your browser. |\n| **Recursive reasoning** | `cortex reason --recursive` — LLM loops: search → reason → search deeper. |\n| **Connectors** | GitHub, Gmail, Calendar, Drive, Slack, Discord, Telegram, Notion. Import + extract facts in one step. |\n| **Provenance** | Every fact tracks source file, line, section, timestamp. Full audit trail. |\n| **Export** | JSON, Markdown, CSV. Your memory is yours. No lock-in. |\n| **MCP server** | `cortex mcp` — stdio or HTTP. Works with Claude Code, Cursor, any MCP client. |\n\n## vs. alternatives\n\n| | Cortex | Mem0 | Zep | Letta |\n|---|:---:|:---:|:---:|:---:|\n| Import existing files | ✅ | ❌ | ❌ | ❌ |\n| Works without LLM | ✅ | ❌ | ❌ | ❌ |\n| Confidence decay | ✅ | ❌ | ❌ | ❌ |\n| Conflict detection | ✅ | ❌ | ❌ | ❌ |\n| Knowledge graph explorer | ✅ | ❌ | ❌ | ❌ |\n| External connectors | ✅ | ❌ | ❌ | ❌ |\n| Recursive reasoning | ✅ | ❌ | ❌ | ❌ |\n| Self-hosted (single binary) | ✅ | 🟡 | 🟡 | 🟡 |\n| Works offline | ✅ | ❌ | ❌ | ❌ |\n| Export / portability | ✅ | ❌ | ❌ | ❌ |\n\n## LLM-powered features (v0.9.0)\n\nLLM features are **optional** — Cortex works fully offline with rule-based extraction. When you add an API key, facts get smarter automatically.\n\n### Without LLM (default for new users)\n\nRule-based extraction handles structured text well (key-value pairs, dates, emails, locations). The governor caps extraction at 10 facts per memory with minimum quality thresholds, preventing garbage accumulation.\n\n```bash\ncortex import ~/notes/ --recursive --extract           # Rules only — works offline\ncortex import ~/notes/ --recursive --extract --no-enrich  # Explicit: skip LLM even if key exists\n```\n\n### With LLM (recommended)\n\nSet one or both API keys for dramatically better fact quality:\n\n```bash\nexport OPENROUTER_API_KEY=\"sk-or-...\"    # For enrichment + classification\nexport GEMINI_API_KEY=\"AI...\"             # For query expansion (free tier)\n```\n\n| Feature | Model | Cost | What it does |\n|---------|-------|------|-------------|\n| **Enrichment** | Grok 4.1 Fast (via OpenRouter) | ~$0.01/file | Finds decisions, relationships, implicit facts rules miss |\n| **Classification** | DeepSeek V3.2 (via OpenRouter) | ~$0.50/20K facts | Reclassifies generic `kv` facts → decision, config, state, etc. |\n| **Query expansion** | Gemini 2.0 Flash | Free | Expands vague queries into better search terms |\n| **Conflict resolution** | Any OpenRouter model | ~$0.01/batch | Auto-resolves contradictory facts |\n\n```bash\n# Import with enrichment (default when OPENROUTER_API_KEY is set)\ncortex import ~/notes/ --recursive --extract\n\n# Bulk reclassify existing kv facts (one-time sweep, ~55 min for 20K facts)\ncortex classify --limit 25000 --batch-size 20 --concurrency 5\n\n# Expand search queries through LLM\ncortex search \"what was that trading thing\" --expand\n\n# Auto-resolve conflicts\ncortex conflicts --resolve llm\n```\n\n**Cost:** \u003c$1/month at typical usage. Full corpus reimport: ~$2-3.\n\n### Upgrading from older versions\n\n\u003e ⚠️ **Critical fix in v0.9.0:** Versions prior to v0.9.0 had a bug where `cortex import --extract` would re-extract facts on **all** recent memories — not just newly imported ones. If you've been running periodic syncs, your database likely has duplicate facts (we saw 74K facts from 1.6K memories drop to 2.5K after fixing). **A clean reimport is strongly recommended.**\n\n```bash\n# Step 1: Clean reimport (wipes DB, re-imports from your files)\ncortex reimport ~/your-notes/ --recursive --extract --no-enrich --force\n\n# Step 2 (optional): Add LLM enrichment for the core files you care about most\nexport OPENROUTER_API_KEY=\"sk-or-...\"\ncortex import ~/your-notes/MEMORY.md --extract    # Full enrichment on key files\n\n# Step 3 (optional): Reclassify generic kv facts with LLM\ncortex classify --limit 50000 --batch-size 20 --concurrency 5\n```\n\n**What changed:** Import now tracks exactly which memories were newly created and only runs extraction/enrichment/classification on those — not the 1000 most recent. Repeated syncs no longer accumulate duplicate facts.\n\n**Expected fact counts after reimport:**\n- ~1-3 facts per memory (rule-only, no LLM) \n- ~3-8 facts per memory (with LLM enrichment)\n- Governor cap: 10 facts per memory maximum\n\nIf your database has \u003e10 facts per memory on average, you have the duplication bug. Reimport to fix it.\n\n### Choosing models\n\nWe benchmarked 6 models across enrichment and classification. Results:\n\n| Task | Best Model | Why |\n|------|-----------|-----|\n| Enrichment | Grok 4.1 Fast | Only model that reliably finds new facts (+26 across 3 test files vs ≤9 for others) |\n| Classification | DeepSeek V3.2 | 76% reclassification, 0 errors, $0.50/20K facts. Batch-size 20 optimal. |\n| Query expansion | Gemini 2.0 Flash | Free tier, 2.3x faster than alternatives, adequate quality for search |\n\nModels that didn't work: MiniMax M2.5 (80% error rate), Codex Mini (8% success), Gemini thinking models (consume JSON in reasoning phase).\n\n## CLI reference\n\n```bash\ncortex import \u003cpath\u003e [--recursive] [--extract]  # Import files or directories\n  [--no-enrich] [--no-classify]                 #   Skip LLM enrichment/classification\n  [--ext md,txt] [--exclude-ext log,tmp]        #   Filter by file extension\ncortex search \u003cquery\u003e [--mode hybrid|bm25|semantic|rrf]  # Search memories\n  [--expand] [--llm google/gemini-2.0-flash]    #   LLM query expansion\ncortex classify [--limit N] [--batch-size 20]   # Reclassify kv facts with LLM\n  [--concurrency 5] [--dry-run]                 #   Parallel batches, preview mode\ncortex conflicts [--resolve llm] [--dry-run]    # Detect/resolve contradictions\ncortex summarize [--cluster N]                  # Consolidate fact clusters\ncortex reason \u003cquery\u003e [--recursive]             # LLM reasoning over memory\ncortex graph [--serve --port 8090]              # Knowledge graph explorer\ncortex stats                                    # What your agent knows\ncortex stale [--days 30]                        # Fading facts\ncortex reinforce \u003cfact-id\u003e                      # Reset decay timer\ncortex connect add \u003cprovider\u003e --config '{...}'  # Add external connector\ncortex connect sync --all [--extract]           # Sync + extract facts\ncortex connect status                           # Connector health\ncortex export [--format json|markdown|csv]      # Take your memory anywhere\ncortex mcp [--embed ollama/nomic-embed-text]    # MCP server for agents\ncortex cleanup                                  # Purge noise\ncortex embed \u003cprovider/model\u003e                   # Generate semantic embeddings\n```\n\n## Semantic search (optional)\n\nBM25 keyword search works out of the box. For semantic search, add an embedding model:\n\n```bash\nollama pull nomic-embed-text\ncortex embed ollama/nomic-embed-text --batch-size 10\ncortex search \"conceptually related query\" --mode hybrid --embed ollama/nomic-embed-text\ncortex search \"conceptually related query\" --mode rrf --embed ollama/nomic-embed-text\n```\n\nSupports Ollama (free/local), OpenAI, DeepSeek, OpenRouter, or any OpenAI-compatible endpoint.\n\n## Architecture\n\n- **Language:** Go 1.24+ — single binary, no runtime dependencies\n- **Storage:** SQLite + FTS5 (pure Go, zero CGO) — `~/.cortex/cortex.db`\n- **Search:** BM25 keyword + optional HNSW ANN for semantic, plus hybrid (WSF) and RRF fusion modes\n- **Extraction:** Rule-based pipeline + optional LLM assist, auto-infer on import\n- **Graph:** Interactive 2D knowledge graph explorer with cluster visualization\n- **Connectors:** GitHub, Gmail, Calendar, Drive, Slack, Discord, Telegram, Notion — with fact extraction\n- **MCP:** stdio + HTTP/SSE transport — 17 tools, 4 resources\n- **Tests:** 1,081 across 15 packages\n\n## Documentation\n\n| Doc | What's in it |\n|-----|-------------|\n| [Getting started](docs/getting-started.md) | Zero to searching in 5 minutes |\n| [Deep dive](docs/CORTEX_DEEP_DIVE.md) | Full technical documentation |\n| [Architecture](docs/ARCHITECTURE.md) | Package structure and data flow |\n| [Connectors guide](docs/connectors.md) | All 8 provider setup guides |\n| [Migration guide](docs/migration.md) | Upgrading from any version to v1.0 |\n| [Release notes](docs/releases/) | Changelog for each version |\n| [Full feature reference](docs/README-full.md) | Benchmarks, presets, chunking details |\n| [Local LLM guide](docs/LOCAL-LLM-PERFORMANCE.md) | Hardware recommendations for local reasoning |\n| [Ops runbook](docs/ops-db-growth-guardrails.md) | Database growth monitoring |\n| [Contributing](CONTRIBUTING.md) | How to contribute |\n| [Brand assets](docs/branding.md) | Logo and visual identity |\n\n## License\n\nMIT — [LICENSE](LICENSE)\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt by \u003ca href=\"https://github.com/hurttlocker\"\u003ehurttlocker\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhurttlocker%2Fcortex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhurttlocker%2Fcortex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhurttlocker%2Fcortex/lists"}