# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.2.1] - 2026-03-16

### Added

- **Cortex JSON export** — Portable JSON format for sharing knowledge packs
  - Filter by project, memory types, date range, min access count
  - Includes memories, entities with graph connections, and project links
  - `memory_export` MCP tool (limit default 100, truncated flag for large datasets)
  - `cortex export` CLI with `--format json|dump`, `--project`, `--output`, `--types`, `--since`, `--min-access`
- **Cortex JSON import** — Import memories from portable JSON with dedup
  - ID-based dedup (skip existing) + optional embedding similarity dedup (>0.92 threshold in merge mode)
  - Re-embeds all imported content (doesn't trust imported vectors)
  - Recreates entity graph and project links from import data
  - `memory_import` MCP tool (dry_run defaults to true for safety)
  - `cortex import` CLI with `--input`, `--project` override, `--merge`, `--dry-run`
- **Full dump export/restore** (CLI only) — Complete database backup
  - Export: SQLite copy + Qdrant snapshot API + Neo4j graph as JSON via Cypher
  - Restore: reverse process with metadata validation
  - `cortex export --format dump --output <dir>` / `cortex import --input <dir>`
- **Import/export tests** — 18 tests covering roundtrip, dedup, dry run, filters, full dump

### Changed

- `cortex init` template now documents `memory_stats`, `memory_share`, `memory_export`, `memory_import` tools
- Branch strategy simplified: removed `dev` branch, PRs go directly to `main`
- GitHub integration: CLAUDE.md now references GitHub MCP tools instead of `gh` CLI

### Fixed

- Neo4j dump restore skips null entity names instead of erroring

## [0.2.0] - 2026-03-16

### Added

- **Tiered entity extraction** — Three-tier system (Regex → NLP → LLM) with automatic fallback
  - Tier 1: Enhanced regex for snake_case, camelCase, PascalCase, quoted identifiers, and verb-pattern relationships
  - Tier 2: NLP via compromise.js with POS tagging, named entity recognition, and embedding-based dedup
  - Tier 3: Claude API extraction with structured JSON output (requires API key)
  - In-memory LRU cache (SHA-256 key, 5 min TTL, 500 entries)
- **Automatic memory extraction** — Cortex observes tool calls and proactively extracts knowledge
  - Conversation buffer with configurable size and debounce timer
  - LLM-powered extraction when API key available, local heuristics as fallback
  - Sentence scoring by technical term density, decision words, pattern words
  - Embedding-based dedup against existing memories (threshold > 0.92)
- **Memory consolidation** — Background process to merge redundant memories
  - Cluster detection via cosine similarity in Qdrant
  - LLM mode: smart merge, contradiction resolution, archival with reasoning
  - Local mode: near-identical dedup (> 0.95), flagging for review (> 0.90)
  - Auto-consolidation timer with configurable interval
  - Audit trail via consolidation_log table
- **Runtime configuration** — `memory_config` tool for live settings changes
  - View full config with storage status and usage stats
  - Set API key, extraction tier, auto-extract, and consolidation at runtime
  - Persists to `~/.cortex/runtime-config.json`
  - API key masked in responses
- **New MCP tools**: `memory_ingest`, `memory_consolidate`, `memory_config`
- **LLM client** — Anthropic API wrapper with retry logic, JSON extraction, token tracking
- **CLI** (`cortex` command) — serve, setup, init, config, consolidate, version, help
- **`cortex init`** — generates Claude Code instructions for project or global CLAUDE.md (idempotent, marker-based updates)
- **npm package** — Published as `@londer/cortex` with proper build step
- **Conventional commits** — commitlint + husky for commit message enforcement
- **Build infrastructure** — TypeScript compilation to `dist/`, declaration maps, source maps
- **Access tracking & staleness scoring** — Memories now track access count, last access time, and staleness score
  - Staleness formula: base decay from days since last access, with frequency and graph-connectivity discounts
  - Ranker applies staleness penalty: `final_score = score * (1 - staleness * 0.3)`
  - Batch staleness recalculation for all memories
  - `CORTEX_STALENESS_THRESHOLD_DAYS` config (default: 90)
- **`memory_stats` MCP tool** — Aggregate statistics: totals, by type/project, most/least accessed, staleness, graph stats
- **`cortex stats` CLI command** — Formatted statistics with live staleness update
- **Ollama support (Tier 2.5)** — Local LLM extraction via Ollama
  - `OllamaClient` with robust JSON repair (markdown fences, trailing commas, single quotes, unquoted keys)
  - `Tier25Ollama` extractor with explicit JSON prompts for smaller models
  - Fallback chain: Tier 3 (Anthropic) → Tier 2.5 (Ollama) → Tier 2 (NLP) → Tier 1 (Regex)
  - Auto-extraction and consolidation use Ollama when Anthropic unavailable
  - `cortex ollama status` and `cortex ollama pull` CLI commands
  - Runtime-settable: `ollama_enabled`, `ollama_url`, `ollama_model` via `memory_config`
  - Config: `CORTEX_OLLAMA_URL`, `CORTEX_OLLAMA_MODEL`, `CORTEX_OLLAMA_ENABLED`
- **Cross-project memory sharing** — Share memories across linked projects
  - Memory visibility: `project-only` (default), `cross-project`, `global`
  - `project_links` table for bidirectional project linking
  - `CROSS_PROJECT` scope tier (1.2x boost) for shared memories
  - `memory_share` MCP tool: promote visibility, link/unlink projects, list links
  - `memory_store` accepts optional `visibility` parameter
  - `memory_search` and `memory_context` respect visibility and include shared/global memories
  - Shared entity auto-detection (logs suggestions to stderr, never auto-shares)
- **`cortex setup --dev`** — Separate dev container management (ports 26333/27687)

### Changed

- `memory_store` now auto-extracts entities when not explicitly provided
- `memory_context` uses tiered extractor instead of basic regex
- SQLite schema extended with source_type, consolidated_from, extraction_confidence, extraction_tier columns
- MCP server version bumped to 0.2.0
- Package renamed to `@londer/cortex`
- Added `CONTRIBUTING.md` with branching strategy, commit rules, and merge policy
- `memory_search`, `memory_context`, `memory_graph_query` now log access for returned results
- `memory_config` output includes Ollama status
- `cortex init` template documents Tier 2.5 (Ollama) and updated fallback chain
- Dev environment fix: `.env.dev` properly configured, `docker:dev` scripts use `--env-file .env.dev`
- `cortex setup` always copies a fresh compose file and supports `--dev` flag

## [0.1.0] - 2026-03-15

### Added

- MCP server with stdio transport for Claude Code integration
- Six core tools: `memory_store`, `memory_search`, `memory_relate`, `memory_graph_query`, `memory_context`, `memory_forget`
- Triple storage backend: Qdrant (vectors), Neo4j (knowledge graph), SQLite (metadata)
- Local embedding pipeline using HuggingFace Transformers.js (`all-MiniLM-L6-v2`, 384 dimensions)
- Tiered memory scoping with automatic project inference and scope boosting
- Multi-source context retrieval combining semantic search, graph traversal, and recency
- Orchestration layer with merge, rank, and dedup logic
- Docker Compose setup for Qdrant and Neo4j
- Test suite covering all layers: embedding, storage, orchestration, and integration