cortex-engine 0.4.1 → 0.5.0

package/hooks/project-board-gate.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# ============================================================================
+# project-board-gate.sh — PreToolUse hook (Bash + MCP tools)
+# ============================================================================
+# Production gate for tracked repos. Configurable requirements before push:
+#   - Board update (gh issue/project commands)
+#   - Ops logging (ops_append via cortex MCP)
+#
+# Config: .claude/state/project-boards.json
+# State:  .claude/state/push-gate-state.txt (session-scoped)
+#
+# The hook does two things depending on what's happening:
+#   1. On board/ops actions → records them in state file
+#   2. On git push → checks state file, blocks if requirements unmet
+# ============================================================================
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+CONFIG_FILE="$PROJECT_DIR/.claude/state/project-boards.json"
+STATE_FILE="$PROJECT_DIR/.claude/state/push-gate-state.txt"
+
+# No config = no gate
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo '{}'
+  exit 0
+fi
+
+# Read config
+CONFIG=$(python3 -c "
+import json, sys
+c = json.load(open('$CONFIG_FILE'))
+print(json.dumps({
+  'enabled': c.get('enabled', True),
+  'strength': c.get('strength', 'block'),
+  'require_board': c.get('on_push', {}).get('require_board_update', True),
+  'require_ops': c.get('on_push', {}).get('require_ops_log', False),
+  'ops_message': c.get('on_push', {}).get('require_ops_log_message', ''),
+  'repos': {k: v for k, v in c.get('repos', {}).items()}
+}))
+" 2>/dev/null || echo '{"enabled":true,"strength":"block","require_board":true,"require_ops":false,"repos":{}}')
+
+ENABLED=$(echo "$CONFIG" | python3 -c "import json,sys; print(json.load(sys.stdin)['enabled'])" 2>/dev/null || echo "True")
+STRENGTH=$(echo "$CONFIG" | python3 -c "import json,sys; print(json.load(sys.stdin)['strength'])" 2>/dev/null || echo "block")
+REQUIRE_BOARD=$(echo "$CONFIG" | python3 -c "import json,sys; print(json.load(sys.stdin)['require_board'])" 2>/dev/null || echo "True")
+REQUIRE_OPS=$(echo "$CONFIG" | python3 -c "import json,sys; print(json.load(sys.stdin)['require_ops'])" 2>/dev/null || echo "False")
+OPS_MESSAGE=$(echo "$CONFIG" | python3 -c "import json,sys; print(json.load(sys.stdin)['ops_message'])" 2>/dev/null || echo "")
+
+if [[ "$ENABLED" == "False" || "$STRENGTH" == "off" ]]; then
+  echo '{}'
+  exit 0
+fi
+
+# Read input
+INPUT=$(cat)
+
+# Detect tool context
+TOOL_NAME=$(echo "$INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null || echo "")
+
+# ═══════════════════════════════════════════════════════════════════════════
+# TRACK: MCP ops_append calls → mark ops logged
+# ═══════════════════════════════════════════════════════════════════════════
+if [[ "$TOOL_NAME" == "mcp__cortex__ops_append" ]]; then
+  mkdir -p "$(dirname "$STATE_FILE")"
+  echo "ops_logged" >> "$STATE_FILE" 2>/dev/null
+  echo '{}'
+  exit 0
+fi
+
+# Only process Bash commands from here
+if [[ "$TOOL_NAME" != "Bash" && -n "$TOOL_NAME" ]]; then
+  echo '{}'
+  exit 0
+fi
+
+COMMAND=$(echo "$INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null || echo "")
+
+# ═══════════════════════════════════════════════════════════════════════════
+# TRACK: gh board/issue commands → mark board updated for detected repo
+# ═══════════════════════════════════════════════════════════════════════════
+if echo "$COMMAND" | grep -qE 'gh\s+(project\s+item|issue\s+(create|comment|close|edit)|pr\s+create)'; then
+  REPOS=$(echo "$CONFIG" | python3 -c "import json,sys; [print(r) for r in json.load(sys.stdin)['repos']]" 2>/dev/null || echo "")
+
+  mkdir -p "$(dirname "$STATE_FILE")"
+  for repo in $REPOS; do
+    if echo "$COMMAND" | grep -qi "$repo"; then
+      echo "board:$repo" >> "$STATE_FILE" 2>/dev/null
+    fi
+  done
+
+  # Fallback: cwd-based detection
+  CWD_REPO=$(basename "$(pwd)" 2>/dev/null || echo "")
+  if echo "$CONFIG" | python3 -c "import json,sys; c=json.load(sys.stdin); exit(0 if '$CWD_REPO' in c['repos'] else 1)" 2>/dev/null; then
+    echo "board:$CWD_REPO" >> "$STATE_FILE" 2>/dev/null
+  fi
+
+  echo '{}'
+  exit 0
+fi
+
+# ═══════════════════════════════════════════════════════════════════════════
+# GATE: git push/merge → check requirements
+# ═══════════════════════════════════════════════════════════════════════════
+IS_GIT_PUSH=false
+if echo "$COMMAND" | grep -qE 'git\s+push'; then
+  IS_GIT_PUSH=true
+fi
+
+if [[ "$IS_GIT_PUSH" == "false" ]]; then
+  echo '{}'
+  exit 0
+fi
+
+# Detect which tracked repo
+DETECTED_REPO=""
+REPOS=$(echo "$CONFIG" | python3 -c "import json,sys; [print(r) for r in json.load(sys.stdin)['repos']]" 2>/dev/null || echo "")
+
+for repo in $REPOS; do
+  if echo "$COMMAND" | grep -qi "$repo"; then
+    DETECTED_REPO="$repo"
+    break
+  fi
+done
+
+if [[ -z "$DETECTED_REPO" ]]; then
+  CMD_DIR=$(echo "$COMMAND" | sed -n 's/.*cd[[:space:]]\+\([^[:space:];&]*\).*/\1/p' | head -1 2>/dev/null || echo "")
+  DIR_BASE=$(basename "${CMD_DIR:-$(pwd)}" 2>/dev/null || echo "")
+
+  for repo in $REPOS; do
+    if [[ "$DIR_BASE" == "$repo" ]]; then
+      DETECTED_REPO="$repo"
+      break
+    fi
+  done
+fi
+
+# Not a tracked repo — allow
+if [[ -z "$DETECTED_REPO" ]]; then
+  echo '{}'
+  exit 0
+fi
+
+# === Check requirements ===
+MISSING=""
+
+if [[ "$REQUIRE_BOARD" == "True" ]]; then
+  if ! grep -q "^board:${DETECTED_REPO}$" "$STATE_FILE" 2>/dev/null; then
+    BOARD_NUM=$(echo "$CONFIG" | python3 -c "import json,sys; print(json.load(sys.stdin)['repos']['$DETECTED_REPO']['board_number'])" 2>/dev/null || echo "?")
+    BOARD_OWNER=$(echo "$CONFIG" | python3 -c "import json,sys; print(json.load(sys.stdin)['repos']['$DETECTED_REPO']['board_owner'])" 2>/dev/null || echo "?")
+    MISSING="${MISSING}\\n**Board update required:**\\n"
+    MISSING="${MISSING}1. Check board: \`gh project item-list $BOARD_NUM --owner $BOARD_OWNER\`\\n"
+    MISSING="${MISSING}2. Update issue: \`gh issue create/comment -R $BOARD_OWNER/$DETECTED_REPO\`\\n"
+    MISSING="${MISSING}3. Move items to reflect current status\\n"
+  fi
+fi
+
+if [[ "$REQUIRE_OPS" == "True" ]]; then
+  if ! grep -q "^ops_logged$" "$STATE_FILE" 2>/dev/null; then
+    MISSING="${MISSING}\\n**Ops log required:**\\n"
+    if [[ -n "$OPS_MESSAGE" ]]; then
+      MISSING="${MISSING}${OPS_MESSAGE}\\n"
+    else
+      MISSING="${MISSING}Call \`ops_append()\` to log what you're pushing and why.\\n"
+    fi
+    MISSING="${MISSING}\`mcp__cortex__ops_append({ content: \"Pushing: [what changed]\", project: \"$DETECTED_REPO\" })\`\\n"
+  fi
+fi
+
+# All requirements met — allow
+if [[ -z "$MISSING" ]]; then
+  echo '{}'
+  exit 0
+fi
+
+REPO_DESC=$(echo "$CONFIG" | python3 -c "import json,sys; print(json.load(sys.stdin)['repos']['$DETECTED_REPO'].get('description',''))" 2>/dev/null || echo "")
+MESSAGE="**[PUSH GATE]** Pushing to \`$DETECTED_REPO\` ($REPO_DESC) — requirements not met:\\n${MISSING}\\nComplete the above, then retry your push.\\n\\n*Config: \`.claude/state/project-boards.json\` — set \`strength\` to \`off\` to disable.*"
+
+if [[ "$STRENGTH" == "block" ]]; then
+  HOOK_EVENT=$(echo "$INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('hook_event_name','PreToolUse'))" 2>/dev/null || echo "PreToolUse")
+  cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "$HOOK_EVENT",
+    "permissionDecision": "deny"
+  },
+  "systemMessage": "$MESSAGE"
+}
+EOF
+else
+  cat <<EOF
+{
+  "systemMessage": "$MESSAGE"
+}
+EOF
+fi

package/hooks/session-lifecycle.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# ============================================================================
+# session-lifecycle.sh — Claude Code Hook
+# ============================================================================
+# Event:    SessionStart
+# Purpose:  Resets session-scoped state files at the start of each session.
+#           Clears cortex telemetry logs and push-gate state so hooks start
+#           fresh without stale data from previous sessions.
+# How:      Truncates .claude/state/cortex-calls.log and push-gate-state.txt.
+# Disable:  Delete this file from .claude/hooks/ — no other config needed.
+# Part of:  fozikio — supports cortex-telemetry.sh and project-board-gate.sh.
+# ============================================================================
+
+STATE_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/state"
+mkdir -p "$STATE_DIR"
+
+# Clear session-scoped state from previous session
+> "$STATE_DIR/cortex-calls.log" 2>/dev/null
+> "$STATE_DIR/push-gate-state.txt" 2>/dev/null
+
+echo '{}'

package/package.json

@@ -1,107 +1,119 @@
-{
-  "name": "cortex-engine",
-  "version": "0.4.1",
-  "description": "Portable cognitive engine for AI agents — storage, embeddings, memory, FSRS, and MCP server",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "cortex-engine": "dist/bin/serve.js",
-    "fozikio": "dist/bin/cli.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "serve": "node dist/bin/serve.js",
-    "test": "node --experimental-vm-modules node_modules/.bin/vitest run",
-    "test:watch": "node --experimental-vm-modules node_modules/.bin/vitest"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "@huggingface/transformers": "^3.8.1",
-    "@modelcontextprotocol/sdk": "^1.6.1",
-    "better-sqlite3": "^11.7.0",
-    "yaml": "^2.7.0"
-  },
-  "peerDependencies": {
-    "@anthropic-ai/sdk": "^0.39.0",
-    "@google-cloud/aiplatform": "^3.12.0",
-    "@google-cloud/firestore": "^7.11.0",
-    "@google-cloud/vertexai": "^1.9.0",
-    "firebase-admin": "^13.0.0",
-    "openai": "^4.77.0"
-  },
-  "peerDependenciesMeta": {
-    "@anthropic-ai/sdk": {
-      "optional": true
-    },
-    "@google-cloud/aiplatform": {
-      "optional": true
-    },
-    "@google-cloud/firestore": {
-      "optional": true
-    },
-    "@google-cloud/vertexai": {
-      "optional": true
-    },
-    "firebase-admin": {
-      "optional": true
-    },
-    "openai": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@anthropic-ai/sdk": "^0.39.0",
-    "@google-cloud/aiplatform": "^3.12.0",
-    "@google-cloud/firestore": "^7.11.0",
-    "@google-cloud/vertexai": "^1.9.0",
-    "@types/better-sqlite3": "^7.6.12",
-    "@types/node": "^22.10.0",
-    "firebase-admin": "^13.0.0",
-    "openai": "^4.77.0",
-    "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
-  },
-  "keywords": [
-    "cortex",
-    "cognitive",
-    "memory",
-    "fsrs",
-    "mcp",
-    "ai-agent",
-    "embeddings"
-  ],
-  "license": "MIT",
-  "author": "Fozikio <hello@fozikio.com>",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Fozikio/cortex-engine.git"
-  },
-  "homepage": "https://github.com/Fozikio/cortex-engine#readme",
-  "files": [
-    "dist",
-    "LICENSE",
-    "README.md"
-  ],
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./stores/firestore": {
-      "import": "./dist/stores/firestore.js",
-      "types": "./dist/stores/firestore.d.ts"
-    },
-    "./stores/sqlite": {
-      "import": "./dist/stores/sqlite.js",
-      "types": "./dist/stores/sqlite.d.ts"
-    },
-    "./mcp": {
-      "import": "./dist/mcp/server.js",
-      "types": "./dist/mcp/server.d.ts"
-    }
-  }
-}
+{
+  "name": "cortex-engine",
+  "version": "0.5.0",
+  "description": "Portable cognitive engine for AI agents — storage, embeddings, memory, FSRS, and MCP server",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "cortex-engine": "dist/bin/serve.js",
+    "fozikio": "dist/bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "serve": "node dist/bin/serve.js",
+    "test": "node --experimental-vm-modules node_modules/.bin/vitest run",
+    "test:watch": "node --experimental-vm-modules node_modules/.bin/vitest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "better-sqlite3": "^11.7.0",
+    "yaml": "^2.7.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@google-cloud/aiplatform": "^3.12.0",
+    "@google-cloud/firestore": "^7.11.0",
+    "@google-cloud/vertexai": "^1.9.0",
+    "firebase-admin": "^13.0.0",
+    "openai": "^4.77.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "@google-cloud/aiplatform": {
+      "optional": true
+    },
+    "@google-cloud/firestore": {
+      "optional": true
+    },
+    "@google-cloud/vertexai": {
+      "optional": true
+    },
+    "firebase-admin": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@google-cloud/aiplatform": "^3.12.0",
+    "@google-cloud/firestore": "^7.11.0",
+    "@google-cloud/vertexai": "^1.9.0",
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.10.0",
+    "firebase-admin": "^13.0.0",
+    "openai": "^4.77.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "cortex",
+    "cognitive",
+    "memory",
+    "fsrs",
+    "mcp",
+    "ai-agent",
+    "embeddings",
+    "fozikio",
+    "persistent-memory",
+    "knowledge-graph",
+    "spaced-repetition"
+  ],
+  "license": "MIT",
+  "author": "Fozikio <hello@fozikio.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Fozikio/cortex-engine.git"
+  },
+  "homepage": "https://github.com/Fozikio/cortex-engine/wiki",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/idapixl"
+  },
+  "files": [
+    "dist",
+    "hooks",
+    "skills",
+    "reflex-rules",
+    "fozikio.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./stores/firestore": {
+      "import": "./dist/stores/firestore.js",
+      "types": "./dist/stores/firestore.d.ts"
+    },
+    "./stores/sqlite": {
+      "import": "./dist/stores/sqlite.js",
+      "types": "./dist/stores/sqlite.d.ts"
+    },
+    "./mcp": {
+      "import": "./dist/mcp/server.js",
+      "types": "./dist/mcp/server.d.ts"
+    }
+  }
+}

package/reflex-rules/cognitive-grounding.yaml

@@ -0,0 +1,17 @@
+name: cognitive-grounding
+version: 1
+tier: recommended
+category: cognitive
+description: Nudge agent to query cortex before substantive cognitive work
+events: [prompt_submit]
+conditions:
+  - field: user_prompt
+    op: regex
+    pattern: '(?i)(evaluat|review|design|assess|analyz|creat|build|architect|plan|propos|critique|audit|diagnos)'
+action: warn
+severity: medium
+message: |
+  This prompt involves substantive cognitive work. Before responding, call query() on the topic to ground your work in accumulated experience.
+override:
+  allow_disable: true
+  allow_downgrade: true

package/reflex-rules/note-about-doing.yaml

@@ -0,0 +1,17 @@
+name: note-about-doing
+version: 1
+tier: custom
+category: cognitive
+description: Suggest capturing new threads of thought with thread_create()
+events: [prompt_submit]
+conditions:
+  - field: user_prompt
+    op: regex
+    pattern: '(?i)(I should|I need to|I want to|let me|I''ll)'
+action: log
+severity: info
+message: |
+  If this is a new thread of thought, consider capturing it with thread_create() rather than just noting it and moving on.
+override:
+  allow_disable: true
+  allow_downgrade: true

package/reflex-rules/observe-first.yaml

@@ -0,0 +1,17 @@
+name: observe-first
+version: 1
+tier: recommended
+category: cognitive
+description: Warn when writing to memory directories without querying cortex first
+events: [file_write, file_edit]
+conditions:
+  - field: file_path
+    op: regex
+    pattern: '(Mind|Journal|memory)'
+action: warn
+severity: medium
+message: |
+  Writing to a memory directory. Have you called observe() or query() first? Memory writes should be grounded in cortex context.
+override:
+  allow_disable: true
+  allow_downgrade: true

package/skills/cortex-query/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: cortex-query
+description: Persistent memory for AI agents — search, record, and build knowledge across sessions using cortex-engine MCP tools
+---
+
+# Cortex Memory — Query & Record
+
+Your agent has persistent memory via cortex-engine. Knowledge survives across sessions — you can recall what you learned last week, track evolving beliefs, and build a knowledge graph over time.
+
+## Core Loop
+
+**Read before you write.** Always check what you already know before adding more.
+
+### Search for knowledge
+
+```
+query("authentication architecture decisions")
+```
+
+Be specific. `query("JWT token expiry policy")` beats `query("auth")`. Results include relevance scores and connected concepts.
+
+After finding a relevant memory, explore around it:
+```
+neighbors(memory_id)
+```
+
+### Record what you learn
+
+**Facts** — things you confirmed or noticed to be true:
+```
+observe("The API rate limits at 1000 req/min per API key, not per user")
+```
+
+**Questions** — things you want to explore but haven't resolved:
+```
+wonder("Why does the sync daemon stall after 300k seconds?")
+```
+
+**Hypotheses** — ideas that might be true but aren't confirmed:
+```
+speculate("Switching to connection pooling might fix the timeout issues")
+```
+
+These are stored separately so questions don't pollute your knowledge base.
+
+### Update beliefs
+
+When your understanding changes:
+```
+believe(concept_id, "Revised understanding based on new evidence", "reason for change")
+```
+
+### Track work across sessions
+
+```
+ops_append("Finished auth refactor, tests passing", project="api-v2")
+```
+
+Next session, pick up where you left off:
+```
+ops_query(project="api-v2")
+```
+
+## Session Pattern
+
+1. **Start:** `query()` the topic you're working on
+2. **During:** `observe()` facts, `wonder()` questions as they come up
+3. **End:** `ops_append()` what you did and what's unfinished
+4. **Periodically:** `dream()` to consolidate observations into long-term memories
+
+## Available Tools
+
+**Write:** observe, wonder, speculate, believe, reflect, digest
+**Read:** query, recall, predict, validate, neighbors, wander
+**Ops:** ops_append, ops_query, ops_update
+**System:** stats, dream
+
+## Setup
+
+```bash
+npm install cortex-engine
+npx fozikio init my-agent
+npx cortex-engine  # starts MCP server
+```
+
+Defaults to local SQLite + Ollama. No cloud accounts needed.

package/skills/cortex-review/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: cortex-review
+description: Code and design review grounded in persistent memory — compares new work against accumulated knowledge and patterns
+---
+
+# Cortex Review
+
+Review code, designs, or proposals by comparing them against your accumulated knowledge in cortex.
+
+## Workflow
+
+### 1. Ground in memory
+
+Before reading the work under review, query cortex for the topic:
+
+```
+query("the domain or system being reviewed")
+```
+
+Read the results. They contain past decisions, patterns, and lessons learned that inform your review.
+
+### 2. Review against context
+
+As you read the work, compare it against what cortex returned:
+
+- **Does it align** with established patterns and past decisions?
+- **Does it diverge** from known approaches — intentionally or accidentally?
+- **Does it introduce** novel patterns worth capturing?
+
+### 3. Record what you find
+
+**New patterns:** If the work introduces something worth remembering:
+```
+observe("The new caching layer uses write-through with 5min TTL — effective for this read-heavy workload")
+```
+
+**Open questions:** If something isn't clear:
+```
+wonder("Why did they bypass the rate limiter for internal services?")
+```
+
+**Belief updates:** If the work changes your understanding:
+```
+believe(concept_id, "Updated understanding", "Evidence from this review")
+```
+
+### 4. Output format
+
+```markdown
+## Review — Grounded in Memory
+
+### Aligned with known patterns
+- [what matches cortex context]
+
+### Divergences
+- [what differs, with reasoning about whether intentional]
+
+### New patterns to capture
+- [novel approaches worth an observe() call]
+
+### Open questions
+- [things to wonder() about]
+```
+
+## Why This Matters
+
+Without memory grounding, every review starts from zero. You'll miss that "we tried this approach 3 weeks ago and it caused latency spikes" or "this pattern was explicitly chosen over the alternative for compliance reasons." Cortex holds that context.