功能描述

Local-first agent memory with Ebbinghaus decay, hybrid search, and MCP tools. Import files, extract facts, search with BM25 + semantic, track confidence over...

使用说明 (SKILL.md)

Cortex — Local-First Agent Memory

Name: Cortex
Author: hurttlocker

The memory layer OpenClaw should have built in.

Cortex is an open-source, import-first memory system for AI agents. Single Go binary, SQLite storage, zero cloud dependencies. It solves the #1 complaint about OpenClaw: agents forget everything after compaction.

GitHub: https://github.com/hurttlocker/cortex Install: brew install hurttlocker/cortex/cortex or download from Releases

Why Cortex?

OpenClaw's default memory is Markdown files. When context fills up, compaction summarizes and destroys specifics. Cortex fixes this:

Problem	Cortex Solution
Compaction loses details	Persistent SQLite DB survives any session
No search — just dump files into context	Hybrid BM25 + semantic search (~16ms keyword, ~52ms semantic)
Everything has equal weight	Ebbinghaus decay — important facts stay, noise fades naturally
Can't import existing files	Import-first: Markdown, text, any file. 8 connectors (GitHub, Gmail, Calendar, Drive, Slack, Notion, Discord, Telegram)
Multi-agent memory leaks	Per-agent scoping built in
Expensive cloud memory services	$0/month. Forever. Local SQLite.

Quick Start

1. Install Cortex

# macOS/Linux (Homebrew)
brew install hurttlocker/cortex/cortex

# Or download binary directly
# https://github.com/hurttlocker/cortex/releases/latest

2. Import Your Memory

# Import OpenClaw's memory files
cortex import ~/clawd/memory/ --extract

# Import specific files
cortex import ~/clawd/MEMORY.md --extract
cortex import ~/clawd/USER.md --extract

3. Search

# Fast keyword search
cortex search "wedding venue" --limit 5

# Semantic search (requires ollama with nomic-embed-text)
cortex search "what decisions did I make about the project" --mode semantic

# Hybrid (recommended)
cortex search "trading strategy" --mode hybrid

4. Use as MCP Server (recommended for OpenClaw)

# Add to your MCP config — Cortex exposes 17 tools + 4 resources
cortex mcp              # stdio mode
cortex mcp --port 8080  # HTTP+SSE mode

Key Features

Ebbinghaus Forgetting Curve

Facts decay at different rates based on type. Identity facts (names, roles) last ~2 years. Temporal facts (events, dates) fade in ~1 week. State facts (status, mood) fade in ~2 weeks. This means search results naturally prioritize what matters — without manual curation.

Hybrid Search

BM25 — instant keyword matching via SQLite FTS5 (~16ms)
Semantic — meaning-based via local embeddings (~52ms)
Hybrid — combines both with reciprocal rank fusion

Fact Extraction

Every imported file gets facts extracted automatically:

Rule-based extraction (zero cost, instant)
Optional LLM enrichment (Grok, Gemini, or any provider — finds facts rules miss)
Auto-classification into 9 types: identity, relationship, preference, decision, temporal, location, state, config, kv

Connectors (Beta)

Pull memory from external sources:

cortex connect sync --provider github --extract
cortex connect sync --provider gmail --extract
cortex connect sync --all --extract

Knowledge Graph

Explore your memory visually:

cortex graph --serve --port 8090
# Opens interactive 2D graph explorer in browser

Self-Cleaning

cortex cleanup --purge-noise  # Remove garbage + duplicates
cortex stale 30               # Find facts not accessed in 30 days
cortex conflicts               # Detect contradictions
cortex conflicts --resolve llm # Auto-resolve with LLM

Integration with OpenClaw

Recommended Search Chain

memory_search → Cortex → QMD → ripgrep → web search

Use OpenClaw's built-in memory_search for conversation history, then Cortex for deep knowledge retrieval.

Wrapper Script

The included scripts/cortex.sh provides shortcuts:

scripts/cortex.sh search "query" 5       # Hybrid search
scripts/cortex.sh stats                    # Memory health
scripts/cortex.sh stale 30                # Stale fact detection
scripts/cortex.sh conflicts               # Contradiction detection
scripts/cortex.sh sync                    # Incremental import
scripts/cortex.sh reimport                # Full wipe + re-import
scripts/cortex.sh compaction              # Pre-compaction state brief

Automated Sync (launchd/systemd)

# Auto-import sessions + sync connectors every 30 min
cortex connect schedule --every 30m --install

Architecture

Language: Go (62,300+ lines, 1,081 tests)
Storage: SQLite + FTS5 + WAL mode
Binary: 19MB, pure Go, zero CGO, zero runtime dependencies
Platforms: macOS (arm64/amd64), Linux (arm64/amd64), Windows (amd64)
MCP: 17 tools + 4 resources (stdio or HTTP+SSE)
Embeddings: Local via Ollama (nomic-embed-text), or OpenAI/DeepSeek/custom
LLM: Optional enrichment via any provider (Grok, Gemini, DeepSeek, OpenRouter)
Scale: Tested to 100K+ memories. At ~20-50/day, won't hit ceiling for 5+ years.
License: MIT

vs Other Memory Tools

	Cortex	Mem0	Zep	LangMem
Deploy	Single binary	Cloud or K8s	Cloud	Python lib
Cost	$0	$19-249/mo	$25/mo+	Infra costs
Privacy	100% local	Cloud by default	Cloud	Depends
Decay	Ebbinghaus (7 rates)	TTL only	Temporal	None
Import	Files + 8 connectors	Chat extraction	Chat/docs	Chat extraction
Search	BM25 + semantic	Vector + graph	Temporal KG	JSON docs
MCP	17 tools native	No	No	No
Dependencies	Zero	Python + cloud	Cloud + credits	Python + LangGraph

Requirements

Cortex binary — install via Homebrew or download from GitHub Releases
Optional: Ollama with nomic-embed-text for semantic search
Optional: LLM API key for enrichment (Grok, Gemini, etc.)
No Python. No Node. No Docker. No cloud account. Just the binary.

v1.1/v1.2 Integration Guide (Wiring for OpenClaw Agents)

When to use `cortex answer` vs `cortex search`

answer — "What do I know about X?" / "Who is Y?" / synthesis questions → single coherent response with citations
search — "Find the file where X is mentioned" / debugging / exploring what exists → ranked result list

Source Boost (config.yaml)

Add to ~/.cortex/config.yaml:

search:
  source_boost:
    - prefix: "memory/"
      weight: 1.5
    - prefix: "file:MEMORY"
      weight: 1.6
    - prefix: "github"
      weight: 1.3
    - prefix: "session:"
      weight: 0.9

Higher weight = more trusted. Daily notes and core files rank above auto-imported sessions.

Search Intent

Use --intent when you know where the answer lives:

--intent memory — personal decisions, preferences, people
--intent connector — code, PRs, emails, external data
--intent import — imported files and documents
No flag = search everything (default, good for discovery)

Lifecycle Runner Schedule

# Nightly dry-run + apply (launchd or cron)
cortex lifecycle run --dry-run > /tmp/lifecycle-plan.log 2>&1
# If anything found, apply:
cortex lifecycle run

Recommended: 3:30 AM daily. First week: dry-run only, review logs.

Policy Presets

Fresh agent (\x3C 500 facts):

policies:
  reinforce_promote:
    min_reinforcements: 3
    min_sources: 2
  decay_retire:
    inactive_days: 90
    confidence_below: 0.25
  conflict_supersede:
    min_confidence_delta: 0.20

Mature agent (2000+ facts):

policies:
  reinforce_promote:
    min_reinforcements: 5
    min_sources: 3
  decay_retire:
    inactive_days: 45
    confidence_below: 0.35
  conflict_supersede:
    min_confidence_delta: 0.10

Post-Import Hygiene

After any bulk import, run:

cortex cleanup --dedup-facts    # Remove near-duplicates
cortex conflicts --auto-resolve  # Resolve contradictions

Recommended OpenClaw Search Chain (Updated)

memory_search → cortex answer (synthesis) → cortex search (pointers) → QMD → ripgrep → web

安全使用建议

What to consider before installing: - The scripts download a prebuilt binary from the project's GitHub releases and install it to ~/bin; the installer does not verify signatures or checksums. Prefer verifying the release checksum or building from source if you need higher assurance. - The tool reads and imports local files (MEMORY.md, memory/). That is expected, but it means your personal notes and agent memory will be read and stored in ~/.cortex/cortex.db. Make a backup if the DB contains sensitive data. - The SKILL.md advertises connectors (Gmail, Drive, Slack, Notion, etc.) and optional LLMs. Those integrations will require provider credentials and will transmit data to external services; the skill metadata does not declare or document the required secrets. Review connector behavior and permission scopes before enabling sync. - The setup may append PATH changes to your shell rc and the project may install scheduled syncs (launchd/systemd) if you use the schedule/install option — expect persistent background activity. Inspect any scheduled-install commands before running them. - The wrapper's 'reimport' command removes the DB file without interactive confirmation — it is destructive for stored memory. Use with caution and keep backups. If you decide to proceed: verify the GitHub release (or build from source), review the binary's release notes and checksums, run the setup in a limited environment first (or container), and only enable connectors after reviewing the exact auth/permission flows.

功能分析

Type: OpenClaw Skill Name: hurttlocker-cortex Version: 4.0.0 This skill is classified as suspicious due to its use of high-risk capabilities, even though they are presented as part of the tool's legitimate functionality. The `scripts/setup.sh` file downloads and executes a binary from a remote GitHub repository, which introduces a supply chain risk. Furthermore, the `SKILL.md` instructions and `scripts/cortex-wrapper.sh` indicate the ability to install persistence mechanisms (e.g., `cortex connect schedule --install` for `launchd`/`systemd` jobs) and modify shell configuration files (`~/.zshrc`, `~/.bashrc`) to add the binary to the system's PATH. While these actions are described as necessary for a memory management tool that syncs data and runs in the background, they represent significant system access and persistence capabilities that could be abused if the `cortex` binary itself were compromised or malicious.

能力评估

ℹ Purpose & Capability

The name/description (local-first memory, single Go binary, SQLite) align with the provided wrapper and setup scripts. The setup downloads a Cortex binary from the stated GitHub repo and installs it to ~/bin, and the wrapper operates on workspace memory files — all coherent with a local memory tool. However, the SKILL.md advertises connectors (GitHub, Gmail, Drive, Slack, Notion, Discord, Telegram) and optional LLM integrations; those require credentials/authorization flows that are not declared in the skill metadata, which is a mismatch (the skill advertises remote connectors but does not declare or request any credentials).

⚠ Instruction Scope

The runtime instructions and scripts direct the agent to read and import local workspace files (MEMORY.md, memory/), which is expected for a memory tool. They also instruct use of 'connect sync' for external providers and show automated sync scheduling (launchd/systemd). Those connector operations imply transmission of user data to external services and require credentials/configs that are not declared; the instructions therefore broaden scope to include external data flows and scheduled background syncs that are not fully documented in the metadata.

ℹ Install Mechanism

Installation is a simple download of a release binary from GitHub releases (expected for a single-binary Go project). The setup script writes the binary to $HOME/bin and optionally appends PATH changes to shell rc files. There is no checksum/signature verification of the downloaded binary in the script (moderate risk). Downloading from GitHub releases is a common pattern but missing verification should be considered.

⚠ Credentials

The skill declares no required environment variables or credentials, which matches the included scripts that run locally. However, SKILL.md documents connectors and optional LLM embedding providers (ollama, OpenAI, etc.) that will need API keys/tokens or local services; those secrets are not declared or explained. This mismatch (advertised external integrations vs. zero declared credentials) reduces transparency and could lead users to provide credentials later without clear upfront guidance.

ℹ Persistence & Privilege

The scripts persist state to $HOME/.cortex/cortex.db and install a binary into $HOME/bin; setup optionally appends PATH changes to ~/.zshrc or ~/.bashrc. The SKILL.md also suggests installing scheduled syncs (launchd/systemd) which could create background tasks. The skill does not request 'always: true' and does not attempt to modify other skills, but it can add files to user shell RC and create scheduled jobs — expected for a CLI tool but worth noting.

版本历史

v4.0.0

v1.2 Belief Lifecycle

v3.1.0

v1.2 Belief Lifecycle + v1.1 Agent Cognition Runtime

v3.0.0

v1.2.0: Belief Lifecycle — fact states, lifecycle policies, lifecycle runner. v1.1: config resolver, source boost, fact dedup, answer mode, conflict auto-resolve, search intent. +4,507 lines, 9 PRs, 17 test packages.

v2.0.0

Complete SKILL.md rewrite — pain-point framing, comparison tables, MCP guide, v1.0 production stats.

v1.1.0

v1.1.0 — Fully rewritten SKILL.md with pain-point framing, comparison tables, MCP integration guide, and updated v1.0 stats (62K+ lines, 1,081 tests, 17 MCP tools, 8 connectors).

v1.0.0

v1.0.0 — Production ready.

元数据

Slug hurttlocker-cortex

版本 4.0.0

许可证 —

累计安装 1

当前安装数 1

历史版本数 6

常见问题

Cortex 是什么？

Local-first agent memory with Ebbinghaus decay, hybrid search, and MCP tools. Import files, extract facts, search with BM25 + semantic, track confidence over... 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 468 次。

如何安装 Cortex？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install hurttlocker-cortex」即可一键安装，无需额外配置。

Cortex 是免费的吗？

是的，Cortex 完全免费（开源免费），可自由下载、安装和使用。

Cortex 支持哪些平台？

Cortex 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 Cortex？

由 marquise（@hurttlocker）开发并维护，当前版本 v4.0.0。

Cortex