{"id":39356937,"url":"https://github.com/julymetodiev/post-cortex","last_synced_at":"2026-02-26T02:55:32.455Z","repository":{"id":324785092,"uuid":"1098441122","full_name":"julymetodiev/post-cortex","owner":"julymetodiev","description":"Post-Cortex provides durable memory infrastructure with automatic knowledge graph construction, intelligent entity extraction, and semantic search powered by local transformer models.","archived":false,"fork":false,"pushed_at":"2026-01-13T20:40:12.000Z","size":649,"stargazers_count":13,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-13T20:59:30.128Z","etag":null,"topics":["ai","ai-memory","graph-rag","knowledge-graph","llm","lock-free","mcp","mcp-server","rust","semantic-search"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/julymetodiev.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":null,"dco":null,"cla":null}},"created_at":"2025-11-17T17:35:21.000Z","updated_at":"2026-01-13T20:40:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/julymetodiev/post-cortex","commit_stats":null,"previous_names":["julymetodiev/post-cortex"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/julymetodiev/post-cortex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julymetodiev%2Fpost-cortex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julymetodiev%2Fpost-cortex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julymetodiev%2Fpost-cortex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julymetodiev%2Fpost-cortex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/julymetodiev","download_url":"https://codeload.github.com/julymetodiev/post-cortex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julymetodiev%2Fpost-cortex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28526580,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"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":["ai","ai-memory","graph-rag","knowledge-graph","llm","lock-free","mcp","mcp-server","rust","semantic-search"],"created_at":"2026-01-18T02:38:32.956Z","updated_at":"2026-02-26T02:55:32.447Z","avatar_url":"https://github.com/julymetodiev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"design/v1.svg\" width=\"128\" height=\"128\" alt=\"Post-Cortex Logo\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ePost-Cortex\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003ePersistent Memory for AI Assistants\u003c/strong\u003e\u003c/p\u003e\n\nPost-Cortex is an MCP server that gives AI assistants long-term memory. It stores conversations, decisions, and insights in a searchable knowledge base with automatic entity extraction.\n\n## Features\n\n- **Persistent Memory** - Conversations survive across sessions\n- **Semantic Search** - Find related content using AI embeddings with HNSW indexing\n- **Graph-RAG** - Search results enriched with entity graph insights and relationship paths\n- **Knowledge Graph** - Automatic entity and relationship extraction\n- **Privacy-First** - All processing runs locally, no external APIs\n- **Fast** - Lock-free Rust architecture, O(log n) vector search, \u003c10ms queries\n- **Flexible Storage** - RocksDB (embedded) or SurrealDB (distributed) with feature parity\n\n## Installation\n\n```bash\n# Homebrew (macOS/Linux)\nbrew install julymetodiev/tap/post-cortex\n\n# Or download binary\ncurl -L https://github.com/julymetodiev/post-cortex/releases/latest/download/pcx-aarch64-apple-darwin -o /usr/local/bin/pcx\nchmod +x /usr/local/bin/pcx\n```\n\n## Quick Start\n\n### 1. Configure Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"post-cortex\": {\n      \"command\": \"pcx\"\n    }\n  }\n}\n```\n\n### 2. Create a Session\n\nAsk Claude: *\"Create a Post-Cortex session for this project\"*\n\n### 3. Use Memory\n\nClaude will automatically store important context and search past knowledge.\n\n### 4. Configure Agent Workflow\n\nFor best results, add a `CLAUDE.md` to your project with memory rules. See **[Usage Guide](docs/USAGE_GUIDE.md)** for:\n- Multi-project setup with workspaces\n- Agent workflow (search → explore → log → respond)\n- Working examples and templates\n\n## MCP Tools (6 Tools)\n\n### `session` - Manage Sessions\n\n```\nsession(action: \"create\", name: \"my-project\", description: \"Project notes\")\nsession(action: \"list\")\n```\n\n### `update_conversation_context` - Store Knowledge\n\n```\n// Single update\nupdate_conversation_context(\n  session_id: \"uuid\",\n  interaction_type: \"decision_made\",\n  content: {\n    \"decision\": \"Use PostgreSQL\",\n    \"rationale\": \"Better JSON support\"\n  }\n)\n\n// Bulk update\nupdate_conversation_context(\n  session_id: \"uuid\",\n  updates: [\n    {interaction_type: \"qa\", content: {...}},\n    {interaction_type: \"code_change\", content: {...}}\n  ]\n)\n```\n\n**Interaction types:** `qa`, `decision_made`, `problem_solved`, `code_change`, `requirement_added`, `concept_defined`\n\n### `semantic_search` - Find Related Content\n\n```\n// Search within session\nsemantic_search(query: \"database decisions\", scope: \"session\", scope_id: \"uuid\")\n\n// Search across workspace\nsemantic_search(query: \"authentication\", scope: \"workspace\", scope_id: \"ws-uuid\")\n\n// Search everything\nsemantic_search(query: \"performance issues\", scope: \"global\")\n\n// Search with recency bias (prioritize recent content)\nsemantic_search(query: \"API changes\", scope: \"session\", scope_id: \"uuid\", recency_bias: 0.5)\n\n// Search with date range\nsemantic_search(\n  query: \"authentication\",\n  scope: \"global\",\n  date_from: \"2024-01-01T00:00:00Z\",\n  date_to: \"2024-12-31T23:59:59Z\"\n)\n```\n\n**Temporal Decay (Recency Bias):**\n\nThe `recency_bias` parameter prioritizes recent content using exponential decay.\n\n| Value | Effect | Use Case |\n|-------|--------|----------|\n| `0.0` (default) | Disabled | Architecture docs, timeless concepts |\n| `0.1 - 0.3` | Very soft bias | General search with slight recency preference |\n| `0.3 - 0.5` | Soft bias | Finding recent solutions, debugging |\n| `0.5 - 1.0` | Moderate bias | Current context, recent issues |\n| `1.0+` | Aggressive bias | Latest changes only |\n\n**Formula:** `adjusted_score = base_score × e^(-λ × days/365)` where λ is the recency_bias value\n\n### `get_structured_summary` - Session Overview\n\n```\n// Get decisions only\nget_structured_summary(session_id: \"uuid\", include: [\"decisions\"])\n\n// Get insights only\nget_structured_summary(session_id: \"uuid\", include: [\"insights\"])\n\n// Get full summary\nget_structured_summary(session_id: \"uuid\", include: [\"all\"])\n```\n\n### `query_conversation_context` - Query Entities\n\n```\n// Entity importance ranking\nquery_conversation_context(\n  session_id: \"uuid\",\n  query_type: \"entity_importance\",\n  parameters: {\"limit\": \"10\"}\n)\n\n// Keyword search\nquery_conversation_context(\n  session_id: \"uuid\",\n  query_type: \"search_updates\",\n  parameters: {\"keyword\": \"API\"}\n)\n```\n\n### `manage_workspace` - Organize Sessions\n\n```\nmanage_workspace(action: \"create\", name: \"trading-project\")\nmanage_workspace(action: \"list\")\nmanage_workspace(action: \"add_session\", workspace_id: \"ws-uuid\", session_id: \"uuid\", role: \"primary\")\nmanage_workspace(action: \"remove_session\", workspace_id: \"ws-uuid\", session_id: \"uuid\")\n```\n\n**Roles:** `primary`, `related`, `dependency`, `shared`\n\n## Daemon Mode\n\nFor multiple Claude instances sharing the same memory:\n\n```bash\n# Start daemon\npcx start\n\n# Check status\npcx status\n\n# Stop daemon\npcx stop\n```\n\nConfigure Claude for HTTP transport:\n```json\n{\n  \"mcpServers\": {\n    \"post-cortex\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:3737/mcp\"\n    }\n  }\n}\n```\n\n## Data Export/Import\n\nBackup and restore your memory database:\n\n```bash\n# Full export\npcx export --output backup.json\n\n# Export with compression\npcx export --output backup.json.gz\n\n# Export specific session\npcx export --output session.json --session \u003cuuid\u003e\n\n# List contents of backup\npcx import --input backup.json --list\n\n# Import (skip existing)\npcx import --input backup.json --skip-existing\n\n# Import (overwrite existing)\npcx import --input backup.json --overwrite\n```\n\n**Compression:** Auto-detected from extension (`.json`, `.json.gz`, `.json.zst`)\n\n## Storage Backends\n\nBoth backends provide **full feature parity** with identical capabilities:\n\n| Feature | RocksDB | SurrealDB |\n|---------|---------|-----------|\n| Vector Search | HNSW O(log n) | HNSW O(log n) |\n| Graph Storage | Persistent | Persistent |\n| Embedding Validation | 384 dimensions | 384 dimensions |\n| Setup | Zero config | Requires server |\n| Distribution | Embedded | Distributed |\n\n### RocksDB (Default)\n\nEmbedded key-value store with in-memory HNSW index, zero configuration:\n\n```bash\npcx start  # Uses ~/.post-cortex/data\n```\n\n**Architecture:** Hybrid storage with RocksDB for persistence and lock-free HNSW index for fast vector search. On startup, embeddings are loaded from disk to rebuild the HNSW index.\n\n### SurrealDB\n\nDistributed graph database with native HNSW support:\n\n1. Start SurrealDB:\n```bash\nsurreal start --user root --pass root\n```\n\n2. Configure `~/.post-cortex/daemon.toml`:\n```toml\nstorage_backend = \"surrealdb\"\nsurrealdb_endpoint = \"ws://localhost:8000\"\nsurrealdb_username = \"root\"\nsurrealdb_password = \"root\"\nsurrealdb_namespace = \"post_cortex\"\nsurrealdb_database = \"main\"\n```\n\n3. Start Post-Cortex:\n```bash\npcx start\n```\n\n**Use SurrealDB when:** You need distributed storage, multiple Post-Cortex instances, or native graph queries.\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PC_HOST` | 127.0.0.1 | Bind address |\n| `PC_PORT` | 3737 | Port |\n| `PC_DATA_DIR` | ~/.post-cortex/data | Storage location |\n| `PC_STORAGE_BACKEND` | rocksdb | Storage: `rocksdb` or `surrealdb` |\n| `PC_SURREALDB_ENDPOINT` | - | SurrealDB WebSocket URL |\n\n## Performance\n\n| Operation | Latency |\n|-----------|---------|\n| Semantic search | 1-7ms |\n| Keyword search | \u003c10ms |\n| Context update | \u003c5ms |\n\n## Development\n\n```bash\n# Build with all features\ncargo build --release --features \"embeddings,surrealdb-storage\"\n\n# Build with RocksDB only\ncargo build --release --features embeddings\n\n# Test\ncargo test\n\n# Run with logging\nRUST_LOG=debug pcx start\n```\n\n### Benchmarks\n\nPost-Cortex includes microbenchmarks for performance regression testing using Criterion:\n\n```bash\n# Run all benchmarks\ncargo bench\n\n# Run specific benchmark\ncargo bench --bench recency_decay\n\n# Save baseline for comparison\ncargo bench -- --save-baseline main\n\n# Compare against baseline\ncargo bench -- --baseline main\n\n# Generate HTML report\ncargo bench -- --output-format html\n```\n\n**Benchmark results (for reference):**\n- Decay calculation: ~317 ps\n- Score adjustment: ~317 ps\n- Batch processing (1000 results): ~74 ns\n\nBenchmarks are automatically run on CI to detect performance regressions.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulymetodiev%2Fpost-cortex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjulymetodiev%2Fpost-cortex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulymetodiev%2Fpost-cortex/lists"}