Skip to content
Back to search

cortex

Persistent local memory for Claude Code. Longer sessions. Cross-session recall. Zero cloud.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hjertefolger--cortex/badge.svg)](/listings/hjertefolger--cortex)

HTML

<a href="/listings/hjertefolger--cortex"><img src="/api/listings/hjertefolger--cortex/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Inside a Claude Code instance:

**Step 1: Add the marketplace**

/plugin marketplace add hjertefolger/cortex

**Step 2: Install the plugin**

<details> <summary><strong>⚠️ Linux users: Click here first</strong></summary>

On Linux, `/tmp` is often a separate filesystem (tmpfs), which causes plugin installation to fail with:

EXDEV: cross-device link not permitted

**Fix**: Set TMPDIR before installing:

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

Then run the install command below in that session.

</details>

/plugin install cortex

**Step 3: Run the setup wizard**

Ask Claude to run the setup skill:

Please setup Cortex (or run /cortex-setup manually)

The wizard will initialize the database, download the embedding model, and configure the statusline.

**Step 4: Customize settings**

Ask Claude to configure your preferences:

Please configure Cortex (or run /cortex-configure manually)

Done! Restart Claude Code to activate the statusline.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 27 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "cortex",
  3. "owner": {
  4. "name": "Tomas Krajcik",
  5. "email": "support@rootdeveloper.dev"
  6. },
  7. "metadata": {
  8. "description": "Persistent local memory for Claude Code. Cross-session recall with vector search, automatic archiving, zero cloud dependencies.",
  9. "version": "2.1.4"
  10. },
  11. "plugins": [
  12. {
  13. "name": "cortex",
  14. "source": "./",
  15. "description": "Persistent local memory for Claude Code. Longer sessions, cross-session recall, zero cloud.",
  16. "category": "memory",
  17. "tags": [
  18. "memory",
  19. "context",
  20. "vector-search",
  21. "embeddings",
  22. "local-first",
  23. "cross-session"
  24. ]
  25. }
  26. ]
  27. }
README.md · README · 509 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Cortex
  2. [![Version](https://img.shields.io/badge/version-2.1.2-blue.svg)](package.json)
  3. [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  4. [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
  5. [![Tests](https://img.shields.io/badge/tests-231%20passing-success.svg)](#testing)
  6. [![TypeScript](https://img.shields.io/badge/typescript-strict-blue.svg)](tsconfig.json)
  7. **Persistent local memory for Claude Code.** Longer sessions. Cross-session recall. Zero cloud.
  8. ```
  9. Ψ 47 ●●○○○ 45% ✓ 5m
  10. ```
  11. ## Why Cortex?
  12. | Problem | Cortex Solution |
  13. |---------|-----------------|
  14. | Session limits hit mid-task | Auto-save on context step (5%) & session end |
  15. | `/clear` wipes everything | SQLite persistence survives clears |
  16. | Re-explaining context every session | Hybrid search recalls relevant memories |
  17. | Cloud memory privacy concerns | 100% local — `~/.cortex/memory.db` |
  18. ## Requirements
  19. - **Node.js**: 18.0.0 or higher
  20. - **Disk Space**: ~500MB (Includes 150MB embedding model cache + database growth)
  21. - **OS**: macOS or Linux (Windows supported via WSL2)
  22. ## Install
  23. Inside a Claude Code instance:
  24. **Step 1: Add the marketplace**
  25. ```
  26. /plugin marketplace add hjertefolger/cortex
  27. ```
  28. **Step 2: Install the plugin**
  29. <details>
  30. <summary><strong>⚠️ Linux users: Click here first</strong></summary>
  31. On Linux, `/tmp` is often a separate filesystem (tmpfs), which causes plugin installation to fail with:
  32. ```
  33. EXDEV: cross-device link not permitted
  34. ```
  35. **Fix**: Set TMPDIR before installing:
  36. ```bash
  37. mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
  38. ```
  39. Then run the install command below in that session.
  40. </details>
  41. ```
  42. /plugin install cortex
  43. ```
  44. **Step 3: Run the setup wizard**
  45. Ask Claude to run the setup skill:
  46. ```
  47. Please setup Cortex (or run /cortex-setup manually)
  48. ```
  49. The wizard will initialize the database, download the embedding model, and configure the statusline.
  50. **Step 4: Customize settings**
  51. Ask Claude to configure your preferences:
  52. ```
  53. Please configure Cortex (or run /cortex-configure manually)
  54. ```
  55. Done! Restart Claude Code to activate the statusline.
  56. ## 🔄 Updating
  57. To update Cortex to the latest version:
  58. **Step 1: Update the marketplace**
  59. ```
  60. /plugin marketplace update cortex
  61. ```
  62. **Step 2: Update the plugin**
  63. ```
  64. /plugin update cortex
  65. ```
  66. **Step 3: Run the setup wizard**
  67. Ask Claude to run the setup skill:
  68. ```
  69. Please setup Cortex (or run /cortex-setup manually)
  70. ```
  71. The wizard will install dependencies and download the embedding model for the new version. Your memories and configuration in `~/.cortex/` are preserved.
  72. **Step 4: Restart Claude Code** to load the new version.
  73. > **Note:** Due to a [known Claude Code issue](https://github.com/anthropics/claude-code/issues/14061),
  74. > always update the marketplace first. After restart, you can ask Claude to verify
  75. > the update by checking if the cached plugin matches the latest release.
  76. ## Statusline
  77. The statusline is configured automatically by `/cortex-setup`. Restart Claude Code after setup to see it.
  78. ```
  79. Ψ 47 ●●○○○ 45% ✓ 5m
  80. ```
  81. - `Ψ` — Cortex identifier
  82. - `47` — Memory fragment count (compact: 1.1K, 10.2M, etc.)
  83. - `●●○○○` — Context usage (filled/empty circles, color-coded)
  84. - `45%` — Context percentage
  85. - `⠋ Saving` — Animated spinner during background save
  86. - `✓ Autosaved` — Success indicator (shows for ~5s after save)
  87. - `✓ 5m` — Time since last save
  88. ## Architecture
  89. ```
  90. ┌──────────────────────────────────────┐
  91. │ Claude Code │
  92. └──────────────┬───────────────────────┘
  93. │ stdin (JSON)
  94. ┌──────────────▼───────────────────────┐
  95. │ Command Router │
  96. │ (src/index.ts) │
  97. └──────────────┬───────────────────────┘
  98. │
  99. ┌───────────────────────────┼───────────────────────────┐
  100. │ │ │
  101. ┌──────────▼──────────┐ ┌──────────▼──────────┐ ┌──────────▼──────────┐
  102. │ Database │ │ Embeddings │ │ Search │
  103. │ (sql.js/WASM) │ │ (Nomic Embed v1.5) │ │ (Vector + FTS5) │
  104. │ + FTS5 + Backup │ │ 768 dims │ │ + RRF Fusion │
  105. └──────────┬──────────┘ └──────────┬──────────┘ └──────────┬──────────┘
  106. │ │ │
  107. └───────────────────────────┼───────────────────────────┘
  108. │
  109. ┌──────────────▼───────────────────────┐
  110. │ ~/.cortex/memory.db │
  111. │ (SQLite + Embeddings) │
  112. └──────────────────────────────────────┘
  113. ```
  114. ### Module Overview
  115. | Module | Lines | Responsibility |
  116. |--------|-------|----------------|
  117. | `index.ts` | 836 | Command router, hooks, statusline |
  118. | `mcp-server.ts` | 850 | MCP protocol, 11 tools exposed |
  119. | `database.ts` | 1143 | SQLite, FTS5, backups, recovery |
  120. | `archive.ts` | 873 | Transcript parsing, chunking |
  121. | `embeddings.ts` | 337 | Nomic Embed v1.5, quantization |
  122. | `search.ts` | 308 | Hybrid search, RRF fusion |
  123. | `config.ts` | 563 | Zod validation, presets |
  124. | `analytics.ts` | 288 | Session tracking, insights |
  125. **Total: ~5,700 lines TypeScript**
  126. ## Search Algorithm
  127. Cortex uses a hybrid search combining three signals:
  128. ```
  129. ┌─────────────────────────────────────────────────────────────────┐
  130. │ Query: "auth flow" │
  131. └─────────────────────────┬───────────────────────────────────────┘
  132. │
  133. ┌────────────────┼────────────────┐
  134. ▼ ▼ ▼
  135. ┌──────────┐ ┌──────────┐ ┌──────────┐
  136. │ Vector │ │ FTS5 │ │ Recency │
  137. │ Search │ │ Keyword │ │ Decay │
  138. │ (60%) │ │ (40%) │ │ (7-day) │
  139. └────┬─────┘ └────┬─────┘ └────┬─────┘
  140. │ │ │
  141. └───────────────┼───────────────┘
  142. ▼
  143. ┌──────────────────┐
  144. │ RRF Fusion │
  145. │ (k=60) │
  146. └────────┬─────────┘
  147. ▼
  148. ┌──────────────────┐
  149. │ Ranked Results │
  150. └──────────────────┘
  151. ```
  152. - **Vector similarity**: Cosine distance on 768-dim embeddings
  153. - **FTS5 keyword**: BM25 ranking with sqlite full-text search
  154. - **RRF fusion**: `1/(k + rank)` aggregation across both lists
  155. - **Recency decay**: 7-day half-life weights recent memories higher
  156. ## Commands
  157. ### User-Invocable Skills
  158. Skills are for multi-step workflows. Atomic operations use MCP tools directly.
  159. | Command | Purpose |
  160. |---------|---------|
  161. | `/cortex-setup` | First-time initialization wizard |
  162. | `/cortex-configure <preset>` | Apply configuration preset |
  163. | `/cortex-manage` | Delete or manage memories |
  164. ### MCP Tools (Claude-invocable)
  165. | Tool | Purpose | Side Effects |
  166. |------|---------|--------------|
  167. | `cortex_recall` | Search memory | Read-only |
  168. | `cortex_remember` | Save specific insight | Creates memory |
  169. | `cortex_save` | Archive full session | Creates memories |
  170. | `cortex_stats` | Get statistics + list projects | Read-only |
  171. | `cortex_restore` | Get restoration context | Read-only |
  172. | `cortex_analytics` | Usage insights | Read-only |
  173. | `cortex_update` | Update memory content/project | Modifies memory |
  174. | `cortex_rename_project` | Bulk rename project | Modifies memories |
  175. | `cortex_delete` | Delete memory | **Destructive** |
  176. | `cortex_forget_project` | Delete project memories | **Destructive** |
  177. #### `cortex_remember` vs `cortex_save`
  178. ```
  179. cortex_remember("JWT refresh tokens must use httpOnly cookies")
  180. → Creates ONE memory fragment from the string
  181. cortex_save()
  182. → Parses transcript, extracts HIGH-VALUE content, creates MULTIPLE fragments
  183. ```
  184. ## Hooks
  185. | Hook | Trigger | Behavior |
  186. |------|---------|----------|
  187. | `SessionStart` | New session | Shows memory count, injects awareness + restoration context |
  188. | `PostToolUse` | After any tool | Monitors context %, triggers auto-save |
  189. | `PreCompact` | Before `/clear` | Archives session, prepares restoration |
  190. ## Configuration
  191. **Location:** `~/.cortex/config.json`
  192. ```json
  193. {
  194. "statusline": {
  195. "enabled": true,
  196. "showFragments": true,
  197. "showLastArchive": true,
  198. "showContext": true
  199. },
  200. "archive": {
  201. "projectScope": true,
  202. "minContentLength": 50
  203. },
  204. "autosave": {
  205. "onSessionEnd": true,
  206. "onPreCompact": true,
  207. "contextStep": {
  208. "enabled": true,
  209. "step": 5
  210. }
  211. },
  212. "restoration": {
  213. "tokenBudget": 2000,
  214. "messageCount": 5,
  215. "turnCount": 3
  216. },
  217. "awareness": {
  218. "enabled": false,
  219. "userName": null,
  220. "timezone": null
  221. }
  222. }
  223. ```
  224. ### Presets
  225. ```bash
  226. /cortex-configure full # All features (statusline, auto-archive, warnings)
  227. /cortex-configure essential # Statusline + auto-archive only
  228. /cortex-configure minimal # Commands only, no automation
  229. ```
  230. ### Key Settings
  231. | Setting | Default | Description |
  232. |---------|---------|-------------|
  233. | `autosave.contextStep.step` | 5 | % context increase to trigger auto-save |
  234. | `autosave.onPreCompact` | true | Archive session before `/compact` or `/clear` |
  235. | `autosave.onSessionEnd` | true | Archive session on exit (`Ctrl+C` x2) |
  236. | `restoration.tokenBudget` | 2000 | Max tokens for key decision restoration |
  237. | `restoration.turnCount` | 3 | Number of raw conversation turns to restore |
  238. | `awareness.enabled` | false | Inject user/date/time at session start and after clear |
  239. | `awareness.userName` | null | User name shown in awareness context |
  240. | `awareness.timezone` | null | IANA timezone (null = auto-detect, `"off"` = omit date/time) |
  241. ## Database Schema
  242. ```sql
  243. CREATE TABLE memories (
  244. id INTEGER PRIMARY KEY AUTOINCREMENT,
  245. content TEXT NOT NULL,
  246. content_hash TEXT UNIQUE, -- SHA256 for deduplication
  247. embedding BLOB NOT NULL, -- 768 × float32 = 3KB
  248. project_id TEXT, -- NULL for global scope
  249. source_session TEXT,
  250. timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
  251. );
  252. CREATE INDEX idx_memories_project_id ON memories(project_id);
  253. CREATE INDEX idx_memories_timestamp ON memories(timestamp);
  254. CREATE INDEX idx_memories_content_hash ON memories(content_hash);
  255. -- Optional FTS5 (graceful fallback to LIKE if unavailable)
  256. CREATE VIRTUAL TABLE memories_fts USING fts5(content);
  257. ```
  258. ### Backup Strategy
  259. - **Auto-backup**: Created on database open
  260. - **Rotation**: Keeps 5 most recent backups
  261. - **Recovery**: Tests each backup until one validates
  262. - **Atomic writes**: temp file + rename pattern
  263. ## Data Storage
  264. ```
  265. ~/.cortex/
  266. ├── memory.db # SQLite database (~2-3MB per 1000 memories)
  267. ├── memory.db.backup.* # Rotated backups (max 5)
  268. ├── config.json # User configuration
  269. ├── analytics.json # Session tracking
  270. └── autoSaveState.json # Transient state
  271. ```
  272. ## Testing
  273. ```bash
  274. npm test
  275. ```
  276. > **Note**: `npm test` runs with **synthetic/fake data** for speed and isolation.
  277. ### Running with Real Data (E2E)
  278. To test against a real production transcript (35MB+):
  279. 1. **Locate a real transcript**:
  280. Find a large `.jsonl` file in your `~/.claude/` directory.
  281. 2. **Place it in tests**:
  282. Copy it to `tests/sample_transcript.jsonl`.
  283. ```bash
  284. cp ~/.claude/your-session-id.jsonl tests/sample_transcript.jsonl
  285. ```
  286. 3. **Run the E2E test**:
  287. ```bash
  288. node --test tests/e2e_transcript.test.js
  289. ```
  290. **200+ tests** covering:
  291. - Database CRUD, deduplication, recovery
  292. - Vector and keyword search (Hybrid RRF)
  293. - Archive parsing, chunking, and value extraction
  294. - MCP tool handlers and stdin processing
  295. - Configuration presets and validation
  296. - Real-world E2E transcript replay
  297. ```
  298. ✔ Analytics Module (14 tests)
  299. ✔ Archive Module (35 tests)
  300. ✔ Config Module (5 tests)
  301. ✔ Database Module (38 tests)
  302. ✔ Embeddings Module (8 tests)
  303. ✔ Search Module (31 tests)
  304. ✔ Integration Tests (21 tests)
  305. ✔ MCP Tool Handlers (5 tests)
  306. ✔ Auto-Save Logic (10 tests)
  307. ✔ E2E Transcript Replay (2 tests)
  308. ℹ tests 231
  309. ℹ suites 54
  310. ℹ pass 231
  311. ℹ fail 0
  312. ```
  313. ## Development
  314. ```bash
  315. npm install # Install dependencies
  316. npm run build # Build index.js + mcp-server.js + copy WASM
  317. npm run build:index # Build main entry only
  318. npm run build:mcp # Build MCP server only
  319. npm run typecheck # TypeScript strict check
  320. npm test # Run test suite
  321. ```
  322. ### Build Output
  323. ```
  324. dist/
  325. ├── index.js # 302KB - Main entry point
  326. ├── mcp-server.js # 277KB - MCP server
  327. └── sql-wasm.wasm # 660KB - SQLite WebAssembly
  328. ```
  329. ### Testing Commands Manually
  330. ```bash
  331. # Test stats command
  332. echo '{"cwd":"/tmp/test"}' | node dist/index.js stats
  333. # Test recall
  334. echo '{"cwd":"/tmp/test"}' | node dist/index.js recall "authentication"
  335. # Test MCP server
  336. echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/mcp-server.js
  337. ```
  338. ## Performance
  339. | Operation | Typical Latency |
  340. |-----------|-----------------|
  341. | Embedding generation | ~100ms |
  342. | Vector search (1000 memories) | ~50ms |
  343. | FTS5 keyword search | ~10ms |
  344. | Hybrid search (combined) | ~100ms |
  345. | Database insert | ~5ms + embedding |
  346. **Memory footprint**: ~50MB base (includes Nomic Embed model)
  347. ## Requirements
  348. - **Node.js**: ≥18.0.0
  349. - **Claude Code**: ≥2.0.12
  350. - **Disk**: ~50MB for model + database
  351. ## Error Handling
  352. Cortex implements defensive error handling:
  353. - **Database corruption**: Auto-recovery from rotated backups
  354. - **FTS5 unavailable**: Graceful fallback to LIKE queries
  355. - **Embedding failures**: Logged, operation continues
  356. - **Stdin parse errors**: Discriminated union with context
  357. - **Missing config**: Auto-created with defaults
  358. ## Security
  359. - **Zero cloud**: All data local to `~/.cortex/`
  360. - **No telemetry**: No external network calls
  361. - **Plaintext storage**: Acceptable for local-only use
  362. - **Deduplication**: SHA256 hash prevents duplicates
  363. ## Troubleshooting
  364. ### Database integrity check
  365. ```
  366. /cortex-manage
  367. ```
  368. ### Reset to defaults
  369. ```bash
  370. rm -rf ~/.cortex
  371. /cortex-setup
  372. ```
  373. ### View raw database
  374. ```bash
  375. sqlite3 ~/.cortex/memory.db "SELECT id, substr(content, 1, 50), timestamp FROM memories ORDER BY timestamp DESC LIMIT 10;"
  376. ```
  377. ### Check embedding model
  378. ```bash
  379. ls -la ~/.cache/huggingface/hub/models--nomic-ai--nomic-embed-text-v1.5/
  380. ```
  381. ## Contributors
  382. Thanks to everyone who has contributed to Cortex!
  383. - [@mikelane](https://github.com/mikelane) — Statusline chaining ([#1](https://github.com/hjertefolger/cortex/pull/1))
  384. - [@djayatillake](https://github.com/djayatillake) — Setup command fix ([#4](https://github.com/hjertefolger/cortex/pull/4))
  385. - [@tkemperman](https://github.com/tkemperman) — MCP notification fix ([#7](https://github.com/hjertefolger/cortex/pull/7))
  386. ## License
  387. MIT
  388. ## Author
  389. **Tomas Krajcik**
  390. - Website: [rootdeveloper.dev](https://rootdeveloper.dev)
  391. - Email: support@rootdeveloper.dev
  392. ---
  393. <p align="center">
  394. <i>Built for developers who value their context.</i>
  395. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.