cortex-claude 0.2.0__tar.gz → 0.4.0__tar.gz

cortex_claude-0.4.0/.claude/hooks/post-tool-use.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# Cortex Claude — PostToolUse hook
+# Auto-captures all tool results to Cortex memory via daemon.
+
+CORTEX_HOME="${CORTEX_HOME:-$HOME/.cortex-claude}"
+SOCKET="$CORTEX_HOME/cortex.sock"
+
+[ ! -S "$SOCKET" ] && exit 0
+
+# Read stdin BEFORE backgrounding
+INPUT=$(cat)
+
+# Background the processing
+(echo "$INPUT" | python3 -c "
+import json, socket, sys, os
+
+data = json.load(sys.stdin)
+tool = data.get('tool_name', '')
+
+if 'cortex' in tool.lower():
+    sys.exit(0)
+
+ti = data.get('tool_input', {})
+tr = str(data.get('tool_response', ''))[:1000]
+cwd = data.get('cwd', '.')
+
+import re
+def strip_private(t):
+    t = re.sub(r'<private>.*?</private>', '', t, flags=re.DOTALL|re.IGNORECASE)
+    return re.sub(r'<private\s*/?>', '', t, flags=re.IGNORECASE).strip()
+
+tr = strip_private(tr)
+for k, v in list(ti.items()):
+    if isinstance(v, str):
+        ti[k] = strip_private(v)
+
+if len(tr) < 20:
+    sys.exit(0)
+
+content = None
+tags = ['auto-capture']
+
+if tool == 'Bash':
+    cmd = str(ti.get('command', ''))[:150]
+    noise = ('ls', 'cd ', 'pwd', 'echo ', 'which ', 'cat ', 'head ', 'tail ', 'mkdir', 'touch ', 'chmod', 'true', 'false', 'test ')
+    if any(cmd.startswith(n) for n in noise) or not cmd:
+        sys.exit(0)
+    content = f'Command: {cmd}\nResult: {tr[:500]}'
+    tags.append('bash')
+
+elif tool == 'Read':
+    path = ti.get('file_path', '')
+    content = f'Read file: {path}\nPreview: {tr[:300]}'
+    tags.append('file-read')
+
+elif tool in ('Edit', 'Write'):
+    path = ti.get('file_path', '')
+    old = str(ti.get('old_string', ''))[:100]
+    new = str(ti.get('new_string', ''))[:100]
+    if old and new:
+        content = f'Edited {path}: replaced \"{old}\" with \"{new}\"'
+    elif tool == 'Write':
+        content = f'Created file: {path}'
+    else:
+        content = f'Modified file: {path}'
+    tags.append('file-change')
+
+elif tool == 'Grep':
+    pattern = ti.get('pattern', '')
+    path = ti.get('path', '')
+    content = f'Search \"{pattern}\" in {path}\nResults: {tr[:500]}'
+    tags.append('search')
+
+elif tool == 'Glob':
+    pattern = ti.get('pattern', '')
+    content = f'File search: {pattern}\nFound: {tr[:500]}'
+    tags.append('search')
+
+elif tool == 'Agent':
+    prompt = str(ti.get('prompt', ''))[:200]
+    content = f'Agent task: {prompt}\nResult: {tr[:500]}'
+    tags.append('agent')
+
+elif tool.startswith('mcp__'):
+    parts = tool.split('__')
+    server = parts[1] if len(parts) > 1 else 'unknown'
+    method = parts[2] if len(parts) > 2 else 'unknown'
+    content = f'MCP {server}.{method}\nInput: {json.dumps(ti)[:200]}\nResult: {tr[:400]}'
+    tags.append('mcp')
+    tags.append(server)
+
+elif tool in ('WebSearch', 'WebFetch'):
+    query = ti.get('query', ti.get('url', ''))
+    content = f'{tool}: {query}\nResult: {tr[:500]}'
+    tags.append('web')
+
+else:
+    content = f'{tool}: {json.dumps(ti)[:150]}\nResult: {tr[:400]}'
+    tags.append(tool.lower())
+
+if not content:
+    sys.exit(0)
+
+sock_path = os.path.expanduser('$SOCKET')
+try:
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    s.settimeout(3)
+    s.connect(sock_path)
+    s.sendall(json.dumps({'action':'save','content':content,'tags':tags,'cwd':cwd}).encode())
+    s.shutdown(socket.SHUT_WR)
+    s.recv(512)
+    s.close()
+except Exception:
+    pass
+") &
+
+exit 0

{cortex_claude-0.2.0 → cortex_claude-0.4.0}/.gitignore

@@ -18,3 +18,5 @@ build/
 *.onnx
 .env
 .env.*
+node_modules/
+src/cortex_claude/web/frontend/node_modules/

{cortex_claude-0.2.0 → cortex_claude-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortex-claude
-Version: 0.2.0
+Version: 0.4.0
 Summary: Local-first, token-efficient memory system for Claude Code via MCP
 Project-URL: Homepage, https://github.com/rafaelaugusto/cortex-claude
 Project-URL: Repository, https://github.com/rafaelaugusto/cortex-claude
@@ -51,7 +51,7 @@ Description-Content-Type: text/markdown
     <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
   </a>
   <a href="pyproject.toml">
-    <img src="https://img.shields.io/badge/version-0.1.0-green.svg" alt="Version">
+    <img src="https://img.shields.io/badge/version-0.4.0-green.svg" alt="Version">
   </a>
   <a href="pyproject.toml">
     <img src="https://img.shields.io/badge/python-%3E%3D3.11-brightgreen.svg" alt="Python">
@@ -62,6 +62,7 @@ Description-Content-Type: text/markdown
   <a href="#quick-start">Quick Start</a> &bull;
   <a href="#how-it-works">How It Works</a> &bull;
   <a href="#tools">Tools</a> &bull;
+  <a href="#web-dashboard">Dashboard</a> &bull;
   <a href="#configuration">Configuration</a> &bull;
   <a href="#benchmarks">Benchmarks</a> &bull;
   <a href="#development">Development</a>
@@ -71,6 +72,14 @@ Description-Content-Type: text/markdown
   Cortex gives Claude Code persistent memory through a local MCP server. Unlike solutions that dump everything into context, Cortex uses <strong>progressive recall</strong> &mdash; a 3-layer retrieval system that returns only what's relevant, using the minimum tokens needed.
 </p>
 
+<br>
+
+<p align="center">
+  <img src="docs/example-ui.gif" alt="Cortex Claude Dashboard" width="800">
+</p>
+
+<p align="center"><em>Interactive knowledge graph &mdash; explore entities, facts, and memories visually.</em></p>
+
 ---
 
 ## The Problem
@@ -113,39 +122,50 @@ The system stops at the cheapest layer that answers the question. **66% fewer to
 - **Background daemon** &mdash; pre-loaded model for instant saves via Unix socket (~0.3s vs ~5s cold start)
 - **Multi-language** &mdash; EN, PT (auto-detected). ES, DE, FR with additional spaCy models
 - **Local-first** &mdash; SQLite + local embeddings + local NLP. Zero API calls, zero network, zero cost
+- **Privacy tags** &mdash; wrap sensitive content in `<private>...</private>` to exclude it from memory
 - **Fully configurable** &mdash; all thresholds, ratios, and behaviors via config.json
 
 ---
 
 ## Quick Start
 
-### Install
+### One-Command Install
 
 ```bash
-pip install cortex-claude
+pip install cortex-claude && cortex-claude setup
+```
+
+That's it. The setup command:
+- Configures the MCP server globally for Claude Code
+- Installs auto-capture hooks (SessionStart + PostToolUse)
+- Creates `~/.claude/CLAUDE.md` with instructions for Claude to use Cortex automatically
+- Downloads the embedding model (~80MB) and spaCy model (~12MB)
+- Starts the background daemon for instant saves
 
-# With Claude-assisted extraction (optional)
+Restart Claude Code and it works in **every project**, no per-project config needed. Claude will automatically consult Cortex before saying "I don't know" and save important context to memory.
+
+### With Claude-assisted extraction (optional)
+
+```bash
 pip install cortex-claude[claude]
 ```
 
-### Configure Claude Code
+### Manual Setup (alternative)
 
-Add a `.mcp.json` to your project root (or `~/.claude.json` for global):
+If you prefer manual configuration, add a `.mcp.json` to your project root:
 
 ```json
 {
   "mcpServers": {
     "cortex": {
       "type": "stdio",
-      "command": "python",
+      "command": "python3",
       "args": ["-m", "cortex_claude"]
     }
   }
 }
 ```
 
-First run downloads the embedding model (~80MB) and spaCy model (~12MB) automatically.
-
 ### Use
 
 Just talk to Claude naturally. Cortex works in the background:
@@ -229,10 +249,46 @@ score = e^(-lambda * days) * (1 + log(access_count))
 
 Recalculated on server startup. Frequently accessed memories get boosted. Stale ones fade.
 
+### Auto-Capture &amp; Hooks
+
+Cortex uses Claude Code hooks to work automatically:
+
+- **SessionStart** &mdash; injects memory stats and known facts when you open a session. Claude knows it has memory and consults it before saying "I don't know".
+- **PostToolUse** &mdash; captures results from **all tools** in background: Bash, Read, Edit, Write, Grep, Glob, Agent, WebSearch, WebFetch, and all third-party MCP tools. No manual save needed.
+- **Background Daemon** &mdash; keeps the embedding model pre-loaded via Unix socket. First save after boot: ~5s (model load). Subsequent saves: **~0.3s**.
+
+All hooks are installed globally by `cortex-claude setup`. No per-project config needed.
+
+### Privacy
+
+Wrap sensitive content in `<private>` tags to exclude it from memory:
+
+```
+The API uses JWT for auth. <private>API_KEY=sk-abc123secret</private> Tokens expire in 24h.
+```
+
+Cortex strips everything between `<private>...</private>` before saving. Works in both manual saves and auto-capture. If the entire content is private, nothing is saved.
+
 ### Hybrid Search
 
 Combines **vector similarity** (semantic meaning) with **FTS5** (exact keyword match) for best recall. FTS5 synced automatically via SQLite triggers.
 
+### Web Dashboard
+
+Interactive knowledge graph visualization and memory browser:
+
+```bash
+cortex-claude web
+# Opens at http://localhost:37800
+```
+
+Features:
+- **Interactive knowledge graph** &mdash; nodes are entities, edges are relations. Click a node to see all its facts and related memories.
+- **Memory browser** &mdash; browse all memories with search, tags, scope, and decay score.
+- **Facts list** &mdash; all extracted triplets, click to focus on the graph node.
+- **Live stats** &mdash; memory count, fact count, scopes, storage size.
+- **Dark theme** &mdash; designed for developers.
+
 ---
 
 ## Cortex vs Traditional Memory (claude-mem, etc.)
@@ -250,10 +306,10 @@ Most memory solutions for AI assistants follow the same pattern: capture observa
 | **Graph navigation** | None | Multi-hop traversal (A &rarr; B &rarr; C) |
 | **Staleness** | No decay | Unused memories lose relevance over time |
 | **Duplicates** | Can accumulate | Auto-merged (cosine similarity > 0.92) |
-| **Auto-capture** | All tool calls via hooks | Bash, Read, Grep, Edit, Write via hooks + background daemon |
+| **Auto-capture** | All tool calls via hooks | All tools (Bash, Read, Edit, Write, Grep, Glob, Agent, MCP, Web) via hooks + daemon |
 | **Session injection** | Full context dump on start | Lightweight facts injection via direct SQLite (<1s) |
 | **Dependencies** | Node.js, Bun, Chroma vector DB | Python + SQLite only (zero external services) |
-| **Web UI** | Viewer on localhost:37777 | CLI only (planned) |
+| **Web UI** | Viewer on localhost:37777 | Interactive graph dashboard on localhost:37800 |
 
 ### Where Cortex wins
 
@@ -267,7 +323,7 @@ Most memory solutions for AI assistants follow the same pattern: capture observa
 ### Where claude-mem wins
 
 - **Broader auto-capture** &mdash; captures all tool calls including MCP tools from third-party servers.
-- **Web viewer** &mdash; real-time memory browser at localhost:37777.
+- **Web viewer** &mdash; real-time memory browser (Cortex has an interactive graph dashboard, but claude-mem's is more mature).
 - **One-command install** &mdash; `npx claude-mem install` vs manual MCP config.
 - **Larger community** &mdash; more stars, Discord, extensive documentation site.
 

{cortex_claude-0.2.0 → cortex_claude-0.4.0}/README.md

@@ -13,7 +13,7 @@
     <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
   </a>
   <a href="pyproject.toml">
-    <img src="https://img.shields.io/badge/version-0.1.0-green.svg" alt="Version">
+    <img src="https://img.shields.io/badge/version-0.4.0-green.svg" alt="Version">
   </a>
   <a href="pyproject.toml">
     <img src="https://img.shields.io/badge/python-%3E%3D3.11-brightgreen.svg" alt="Python">
@@ -24,6 +24,7 @@
   <a href="#quick-start">Quick Start</a> &bull;
   <a href="#how-it-works">How It Works</a> &bull;
   <a href="#tools">Tools</a> &bull;
+  <a href="#web-dashboard">Dashboard</a> &bull;
   <a href="#configuration">Configuration</a> &bull;
   <a href="#benchmarks">Benchmarks</a> &bull;
   <a href="#development">Development</a>
@@ -33,6 +34,14 @@
   Cortex gives Claude Code persistent memory through a local MCP server. Unlike solutions that dump everything into context, Cortex uses <strong>progressive recall</strong> &mdash; a 3-layer retrieval system that returns only what's relevant, using the minimum tokens needed.
 </p>
 
+<br>
+
+<p align="center">
+  <img src="docs/example-ui.gif" alt="Cortex Claude Dashboard" width="800">
+</p>
+
+<p align="center"><em>Interactive knowledge graph &mdash; explore entities, facts, and memories visually.</em></p>
+
 ---
 
 ## The Problem
@@ -75,39 +84,50 @@ The system stops at the cheapest layer that answers the question. **66% fewer to
 - **Background daemon** &mdash; pre-loaded model for instant saves via Unix socket (~0.3s vs ~5s cold start)
 - **Multi-language** &mdash; EN, PT (auto-detected). ES, DE, FR with additional spaCy models
 - **Local-first** &mdash; SQLite + local embeddings + local NLP. Zero API calls, zero network, zero cost
+- **Privacy tags** &mdash; wrap sensitive content in `<private>...</private>` to exclude it from memory
 - **Fully configurable** &mdash; all thresholds, ratios, and behaviors via config.json
 
 ---
 
 ## Quick Start
 
-### Install
+### One-Command Install
 
 ```bash
-pip install cortex-claude
+pip install cortex-claude && cortex-claude setup
+```
+
+That's it. The setup command:
+- Configures the MCP server globally for Claude Code
+- Installs auto-capture hooks (SessionStart + PostToolUse)
+- Creates `~/.claude/CLAUDE.md` with instructions for Claude to use Cortex automatically
+- Downloads the embedding model (~80MB) and spaCy model (~12MB)
+- Starts the background daemon for instant saves
 
-# With Claude-assisted extraction (optional)
+Restart Claude Code and it works in **every project**, no per-project config needed. Claude will automatically consult Cortex before saying "I don't know" and save important context to memory.
+
+### With Claude-assisted extraction (optional)
+
+```bash
 pip install cortex-claude[claude]
 ```
 
-### Configure Claude Code
+### Manual Setup (alternative)
 
-Add a `.mcp.json` to your project root (or `~/.claude.json` for global):
+If you prefer manual configuration, add a `.mcp.json` to your project root:
 
 ```json
 {
   "mcpServers": {
     "cortex": {
       "type": "stdio",
-      "command": "python",
+      "command": "python3",
       "args": ["-m", "cortex_claude"]
     }
   }
 }
 ```
 
-First run downloads the embedding model (~80MB) and spaCy model (~12MB) automatically.
-
 ### Use
 
 Just talk to Claude naturally. Cortex works in the background:
@@ -191,10 +211,46 @@ score = e^(-lambda * days) * (1 + log(access_count))
 
 Recalculated on server startup. Frequently accessed memories get boosted. Stale ones fade.
 
+### Auto-Capture &amp; Hooks
+
+Cortex uses Claude Code hooks to work automatically:
+
+- **SessionStart** &mdash; injects memory stats and known facts when you open a session. Claude knows it has memory and consults it before saying "I don't know".
+- **PostToolUse** &mdash; captures results from **all tools** in background: Bash, Read, Edit, Write, Grep, Glob, Agent, WebSearch, WebFetch, and all third-party MCP tools. No manual save needed.
+- **Background Daemon** &mdash; keeps the embedding model pre-loaded via Unix socket. First save after boot: ~5s (model load). Subsequent saves: **~0.3s**.
+
+All hooks are installed globally by `cortex-claude setup`. No per-project config needed.
+
+### Privacy
+
+Wrap sensitive content in `<private>` tags to exclude it from memory:
+
+```
+The API uses JWT for auth. <private>API_KEY=sk-abc123secret</private> Tokens expire in 24h.
+```
+
+Cortex strips everything between `<private>...</private>` before saving. Works in both manual saves and auto-capture. If the entire content is private, nothing is saved.
+
 ### Hybrid Search
 
 Combines **vector similarity** (semantic meaning) with **FTS5** (exact keyword match) for best recall. FTS5 synced automatically via SQLite triggers.
 
+### Web Dashboard
+
+Interactive knowledge graph visualization and memory browser:
+
+```bash
+cortex-claude web
+# Opens at http://localhost:37800
+```
+
+Features:
+- **Interactive knowledge graph** &mdash; nodes are entities, edges are relations. Click a node to see all its facts and related memories.
+- **Memory browser** &mdash; browse all memories with search, tags, scope, and decay score.
+- **Facts list** &mdash; all extracted triplets, click to focus on the graph node.
+- **Live stats** &mdash; memory count, fact count, scopes, storage size.
+- **Dark theme** &mdash; designed for developers.
+
 ---
 
 ## Cortex vs Traditional Memory (claude-mem, etc.)
@@ -212,10 +268,10 @@ Most memory solutions for AI assistants follow the same pattern: capture observa
 | **Graph navigation** | None | Multi-hop traversal (A &rarr; B &rarr; C) |
 | **Staleness** | No decay | Unused memories lose relevance over time |
 | **Duplicates** | Can accumulate | Auto-merged (cosine similarity > 0.92) |
-| **Auto-capture** | All tool calls via hooks | Bash, Read, Grep, Edit, Write via hooks + background daemon |
+| **Auto-capture** | All tool calls via hooks | All tools (Bash, Read, Edit, Write, Grep, Glob, Agent, MCP, Web) via hooks + daemon |
 | **Session injection** | Full context dump on start | Lightweight facts injection via direct SQLite (<1s) |
 | **Dependencies** | Node.js, Bun, Chroma vector DB | Python + SQLite only (zero external services) |
-| **Web UI** | Viewer on localhost:37777 | CLI only (planned) |
+| **Web UI** | Viewer on localhost:37777 | Interactive graph dashboard on localhost:37800 |
 
 ### Where Cortex wins
 
@@ -229,7 +285,7 @@ Most memory solutions for AI assistants follow the same pattern: capture observa
 ### Where claude-mem wins
 
 - **Broader auto-capture** &mdash; captures all tool calls including MCP tools from third-party servers.
-- **Web viewer** &mdash; real-time memory browser at localhost:37777.
+- **Web viewer** &mdash; real-time memory browser (Cortex has an interactive graph dashboard, but claude-mem's is more mature).
 - **One-command install** &mdash; `npx claude-mem install` vs manual MCP config.
 - **Larger community** &mdash; more stars, Discord, extensive documentation site.
 

{cortex_claude-0.2.0 → cortex_claude-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cortex-claude"
-version = "0.2.0"
+version = "0.4.0"
 description = "Local-first, token-efficient memory system for Claude Code via MCP"
 readme = "README.md"
 license = { text = "MIT" }

cortex_claude-0.4.0/src/cortex_claude/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

cortex_claude-0.4.0/src/cortex_claude/__main__.py

@@ -0,0 +1,34 @@
+import sys
+
+
+def main() -> None:
+    cmd = sys.argv[1] if len(sys.argv) > 1 else ""
+
+    if cmd == "setup":
+        from cortex_claude.setup import run_setup
+        run_setup()
+    elif cmd == "daemon":
+        _run_daemon()
+    elif cmd == "web":
+        port = int(sys.argv[2]) if len(sys.argv) > 2 else 37800
+        from cortex_claude.web.server import run_web
+        run_web(port=port)
+    else:
+        from cortex_claude.server.app import mcp, _init_engine
+        _init_engine()
+        mcp.run(transport="stdio")
+
+
+def _run_daemon() -> None:
+    import asyncio
+    from cortex_claude.daemon import CortexDaemon
+
+    daemon = CortexDaemon()
+    try:
+        asyncio.run(daemon.start())
+    except KeyboardInterrupt:
+        daemon.close()
+
+
+if __name__ == "__main__":
+    main()

{cortex_claude-0.2.0 → cortex_claude-0.4.0}/src/cortex_claude/core/engine.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Literal
 
 from cortex_claude.core.decay import recalculate_decay_scores
+from cortex_claude.core.privacy import is_fully_private, strip_private
 from cortex_claude.core.scope_manager import ScopeManager
 from cortex_claude.core.token_budget import TokenBudget
 from cortex_claude.embeddings import EmbeddingEngine, count_tokens
@@ -58,6 +59,11 @@ class CortexEngine:
         scope: str | None = None,
         cwd: str = ".",
     ) -> SaveResult:
+        if is_fully_private(content):
+            return SaveResult(memory_id="", scope="", tokens_stored=0)
+
+        content = strip_private(content)
+
         write_scope = scope or self._scope_manager.get_write_scope(cwd)
         conn = self._storage.get_database(write_scope)
 

cortex_claude-0.4.0/src/cortex_claude/core/privacy.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import re
+
+PRIVATE_PATTERN = re.compile(r"<private>.*?</private>", re.DOTALL | re.IGNORECASE)
+PRIVATE_BLOCK_PATTERN = re.compile(r"<private\s*/?>", re.IGNORECASE)
+
+
+def strip_private(text: str) -> str:
+    text = PRIVATE_PATTERN.sub("", text)
+    text = PRIVATE_BLOCK_PATTERN.sub("", text)
+    return text.strip()
+
+
+def contains_private(text: str) -> bool:
+    return bool(PRIVATE_PATTERN.search(text) or PRIVATE_BLOCK_PATTERN.search(text))
+
+
+def is_fully_private(text: str) -> bool:
+    stripped = strip_private(text)
+    return len(stripped) == 0