@porast1/mcp-cognitive 1.0.0 → 1.1.0

package/AGENT_INSTRUCTIONS.md

@@ -0,0 +1,81 @@
+# MCP Cognitive — Agent Instructions
+
+> Copy this section into your project's `.github/copilot-instructions.md` or equivalent AI instructions file.
+> It tells AI agents what tools are available, when to use them, and how.
+
+---
+
+## Cognitive Memory (mcp-cognitive)
+
+The project uses an MCP server (`mcp-cognitive`) backed by Weaviate hybrid search for persistent AI knowledge.
+Facts survive between sessions — recall them before searching the codebase.
+
+### Tool Inventory (18 tools)
+
+#### CRUD — Core Knowledge
+
+| Tool               | When to use                                                                                               | Key params                                                                                                                       |
+| ------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `cognitive_recall` | **At task start** — before codebase research. Search facts by semantic query, filter by module/tags/type. | `query?` (optional — omit for filter-only), `module?`, `modules?` (multi-module parallel), `tags?`, `types?`, `agent?`, `limit?` |
+| `cognitive_store`  | After discovering an insight worth remembering. Use `dryRun=true` first to check for duplicates.          | `fact`, `type` (invariant/policy/convention/observation/ephemeral), `module`, `citations?`, `tags?`, `confidence?`, `dryRun?`    |
+| `cognitive_update` | To patch an existing fact in-place (confidence, tags, citations). Preserves ID and history.               | `id` (UUID), `confidence?`, `type?`, `module?`, `tags?`, `addTags?`, `removeTags?`, `citations?`                                 |
+| `cognitive_forget` | To archive outdated/incorrect facts (soft-delete with reason).                                            | `id` (UUID), `reason`                                                                                                            |
+
+#### Search & Discovery
+
+| Tool                              | When to use                                                          | Key params                                                                       |
+| --------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `cognitive_search_documents`      | Find indexed docs (DDD, architecture, guides).                       | `query`, `docType?`, `module?`, `project?`                                       |
+| `cognitive_search_code_artifacts` | Find indexed code by semantic meaning or keyword.                    | `query`, `module?`, `layer?`, `artifactType?`                                    |
+| `cognitive_search_test_artifacts` | Find indexed tests by description or module.                         | `query`, `module?`, `testType?`                                                  |
+| `cognitive_correlate`             | Cross-collection traceability: docs ↔ code ↔ tests. Gap detection. | `sourceId` or `sourceQuery`, `sourceCollection`, `targetCollections?`, `module?` |
+
+#### Indexing
+
+| Tool                            | When to use                                           | Key params                                                   |
+| ------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
+| `cognitive_store_document`      | Index a markdown doc chunk (auto-dedup via checksum). | `content`, `filePath`, `docType`, `project`, `checksum`      |
+| `cognitive_store_code_artifact` | Index a TypeScript file with metadata.                | `content`, `filePath`, `project`, `artifactType`, `checksum` |
+| `cognitive_store_test_artifact` | Index a test file with describe/it blocks.            | `content`, `filePath`, `project`, `testType`, `checksum`     |
+
+#### Analysis & Maintenance
+
+| Tool                 | When to use                                                                              | Key params                                         |
+| -------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `cognitive_reason`   | Need a synthesized answer, not raw facts. Groups by module/type, detects contradictions. | `question`, `modules?`, `depth?` (shallow/deep)    |
+| `cognitive_timeline` | Review what was learned during a period. Chronological, grouped by day.                  | `since?`, `until?`, `module?`, `status?`, `order?` |
+| `cognitive_stats`    | Quick overview before deciding what to do. Counts, top tags, activity.                   | `module?`                                          |
+| `cognitive_verify`   | After refactors — check if citation file paths still exist.                              | `factId?` (omit = verify all)                      |
+| `cognitive_audit`    | Periodic quality check. Finds stale facts, broken citations, duplicates. Expensive.      | _(no params)_                                      |
+| `cognitive_compact`  | Merge duplicate facts. Preview first, then execute.                                      | `mode` (preview/execute), `factIdA?`, `factIdB?`   |
+| `cognitive_health`   | Check Weaviate infrastructure is running.                                                | _(no params)_                                      |
+
+### Workflow Rules
+
+1. **Recall BEFORE search** — always call `cognitive_recall` at task start to check for cached knowledge before grepping the codebase.
+2. **Store with citations** — include `file:line` references so facts can be verified later.
+3. **Use `dryRun`** — before storing, call `cognitive_store({ ..., dryRun: true })` to avoid duplicates.
+4. **Fact types matter:**
+   - `invariant` (confidence: 1.0) — permanent architecture rules
+   - `policy` (0.9–0.95) — business decisions that may change
+   - `convention` (0.85–0.9) — team conventions, audit every 6 months
+   - `observation` (0.7–0.8) — debugging insights, re-verify in 30 days
+   - `ephemeral` (any) — temporary notes, auto-expire in 7 days
+5. **Update > Supersede** — use `cognitive_update` to patch facts. Only use `store({ supersedes })` when the fact text itself changed fundamentally.
+6. **Forget with reason** — when archiving, always explain why so the knowledge graph stays auditable.
+
+### Example: Typical Agent Flow
+
+```
+1. cognitive_recall({ query: "form validation rules", module: "identity" })
+2. ... analyze codebase ...
+3. cognitive_store({
+     fact: "Registration form uses per-field Zod validation, not form-level",
+     type: "convention",
+     module: "identity",
+     citations: [{ file: "apps/web/lib/modules/identity/...", line: 42 }],
+     tags: ["forms", "validation", "zod"],
+     dryRun: true
+   })
+4. // If no duplicates found: re-run without dryRun
+```

package/README.md

@@ -1,142 +1,346 @@
-# @osobisty/mcp-cognitive
-
-Universal MCP server for AI knowledge persistence with SQLite fallback and Weaviate hybrid search.
-
-## Features
-
-- 🧠 **SQLite fallback** — Works offline, no infrastructure required
-- 🔍 **Weaviate hybrid search** — BM25 keyword + vector embeddings (optional)
-- 🏢 **Multi-tenancy** — Isolate data per project via `WEAVIATE_TENANT` env var
-- 🛠️ **CLI tools** — Migration, sync, audit, verification
-- 📚 **4 MCP Tools** — `cognitive_recall`, `cognitive_store`, `cognitive_verify`, `cognitive_audit`
-
-## Installation
-
-```bash
-npm install @osobisty/mcp-cognitive
-# or
-pnpm add @osobisty/mcp-cognitive
-```
-
-## Configuration
-
-Add to `.vscode/mcp.json`:
-
-```jsonc
-{
-  "servers": {
-    "cognitive": {
-      "command": "node",
-      "args": ["./node_modules/@osobisty/mcp-cognitive/dist/server.js"],
-      "env": {
-        "COGNITIVE_DB_PATH": ".cognitive/facts.sqlite",
-        "WORKSPACE_ROOT": "${workspaceFolder}",
-        "USE_WEAVIATE": "true",
-        "WEAVIATE_URL": "localhost:8200",
-        "WEAVIATE_TENANT": "myproject"  // 🔑 Project isolation
-      }
-    }
-  }
-}
-```
-
-> **Note:** Works with pnpm, npm, yarn - `node_modules/` path is standard across package managers.
-
-## Environment Variables
-
-| Variable          | Default                     | Description                       |
-| ----------------- | --------------------------- | --------------------------------- |
-| COGNITIVE_DB_PATH | `.cognitive/facts.sqlite`   | SQLite database location          |
-| WORKSPACE_ROOT    | `process.cwd()`             | Project root (for relative paths) |
-| USE_WEAVIATE      | `false`                     | Enable Weaviate hybrid search     |
-| WEAVIATE_URL      | `localhost:8200`            | Weaviate connection URL           |
-| WEAVIATE_TENANT   | `default`                   | Tenant name for multi-tenancy     |
-
-## CLI Tools
-
-```bash
-# Migrate SQLite → Weaviate
-npx mcp-cognitive-migrate
-
-# Sync markdown docs to knowledge base
-npx mcp-cognitive-sync
-
-# Audit stale facts (broken citations)
-npx mcp-cognitive-audit
-
-# Verify citations exist
-npx mcp-cognitive-verify
-
-# Detect stale facts
-npx mcp-cognitive-stale
-```
-
-## Multi-Tenancy
-
-Use `WEAVIATE_TENANT` to isolate data between projects:
-
-```jsonc
-// Project A (.vscode/mcp.json)
-"WEAVIATE_TENANT": "project-a"
-
-// Project B (.vscode/mcp.json)
-"WEAVIATE_TENANT": "project-b"
-```
-
-Both projects share the same Weaviate instance (~1GB RAM) but have isolated data.
-
-## MCP Tools
-
-### `cognitive_recall`
-
-Search facts with filters.
-
-**Parameters:**
-- `query` (string): Search query
-- `module` (optional): Filter by module
-- `types` (optional): Filter by classification
-- `minConfidence` (optional): Minimum confidence score
-
-**Returns:** Array of `Fact` objects with metadata.
-
-### `cognitive_store`
-
-Store new fact.
-
-**Parameters:**
-- `fact` (string): Knowledge statement
-- `module` (string): Module name
-- `classification` (string): `invariant | policy | convention | observation`
-- `citations` (array): File:line references
-- `tags` (array): Keywords
-
-**Returns:** Created fact with ID.
-
-### `cognitive_verify`
-
-Verify citations exist.
-
-**Parameters:**
-- `factId` (string): Fact to verify
-
-**Returns:** Verification status + broken citations.
-
-### `cognitive_audit`
-
-Audit all facts for stale citations.
-
-**Returns:** Summary + list of stale facts.
-
-## Architecture
-
-```
-CognitiveStore (interface)
-├── SqliteStore (fallback)
-└── WeaviateStore (hybrid search)
-    ├── BM25 keyword search
-    └── Vector embeddings (text2vec-transformers)
-```
-
-## License
-
-MIT
+# @porast1/mcp-cognitive
+
+Universal [MCP](https://modelcontextprotocol.io/) server that gives AI agents persistent, searchable memory backed by [Weaviate](https://weaviate.io/) hybrid search (BM25 keyword + vector embeddings + cross-encoder reranking).
+
+Store facts, documents, code artifacts, and test artifacts. Query them with semantic search, filter by module/type/tags, reason across knowledge, detect contradictions, and keep the database healthy — all from 18 MCP tools.
+
+## Why
+
+LLM agents lose context between sessions.  
+`mcp-cognitive` makes knowledge survive: conventions, architecture decisions, debugging insights, domain rules — anything worth remembering.
+
+- **Hybrid search** — BM25 keyword matching + transformer vector embeddings + reranking. Not just text search.
+- **Multi-tenancy** — one Weaviate instance, many projects. Data fully isolated via `WEAVIATE_TENANT`.
+- **4 collections** — `CognitiveFact`, `DocumentChunk`, `CodeArtifact`, `TestArtifact`. Facts, docs, code, tests.
+- **18 MCP tools** — CRUD, search, reasoning, audit, correlation, compaction, timeline, stats.
+- **Agent profiles** — tune recall per agent role (architect vs. tester vs. debugger).
+- **Pattern detection** — auto-detect conventions from git diffs via post-commit hooks.
+- **Zero vendor lock-in** — port/adapter architecture. Weaviate is the sole adapter today.
+
+---
+
+## Quick Start
+
+### 1. Start Weaviate
+
+```bash
+git clone https://github.com/porast1/weaviate-dev-stack
+cd weaviate-dev-stack
+docker-compose up -d
+# ~1.5 GB RAM (Weaviate + text2vec-transformers + reranker-transformers)
+```
+
+### 2. Install the package
+
+```bash
+npm install @porast1/mcp-cognitive
+# or
+pnpm add @porast1/mcp-cognitive
+```
+
+### 3. Configure VS Code / Copilot
+
+Copy the template config to your project:
+
+```bash
+# Copy config templates (mcp.jsonc, profiles.json, .env.example)
+cp -r ./node_modules/@porast1/mcp-cognitive/config/ ./.cognitive/
+
+# Copy .env.example to project root
+cp ./.cognitive/.env.example ./.env
+```
+
+Then add to `.vscode/mcp.json` (or copy from `.cognitive/mcp.jsonc`):
+
+```jsonc
+{
+  "servers": {
+    "cognitive": {
+      "command": "node",
+      "args": ["./node_modules/@porast1/mcp-cognitive/dist/server.js"],
+      "env": {
+        "WEAVIATE_URL": "localhost:8200",
+        "WEAVIATE_TENANT": "myproject", // isolates your data
+        "WORKSPACE_ROOT": "${workspaceFolder}",
+        "COGNITIVE_PROFILES_FILE": "./.cognitive/profiles.json", // optional
+      },
+    },
+  },
+}
+```
+
+### 4. Done
+
+The MCP server registers 18 tools automatically. Your AI agent can now store and recall knowledge.
+
+---
+
+## Environment Variables
+
+Full reference in [`config/.env.example`](config/.env.example). Key variables:
+
+| Variable                  | Default          | Description                                           |
+| ------------------------- | ---------------- | ----------------------------------------------------- |
+| `WEAVIATE_URL`            | `localhost:8200` | Weaviate HTTP endpoint                                |
+| `WEAVIATE_TENANT`         | _(none)_         | Tenant name for data isolation (strongly recommended) |
+| `WEAVIATE_GRPC_PORT`      | _(auto)_         | gRPC port override                                    |
+| `WORKSPACE_ROOT`          | `process.cwd()`  | Project root for resolving citation file paths        |
+| `COGNITIVE_PROJECT`       | `default`        | Project identifier for multi-project tagging          |
+| `COGNITIVE_PROFILES_FILE` | _(none)_         | Path to agent profiles JSON                           |
+| `COGNITIVE_PATTERNS_FILE` | _(none)_         | Path to pattern definitions for post-commit hook      |
+| `COGNITIVE_MAX_ARCHIVES`  | `20`             | Max archive operations per session (safety guard)     |
+| `COGNITIVE_MAX_COMPACTS`  | `10`             | Max compact operations per session (safety guard)     |
+| `COGNITIVE_ALLOW_RESET`   | `false`          | Enable `resetTenant()` — **test environments only**   |
+
+---
+
+## Tools Reference
+
+### Core Knowledge (CRUD)
+
+| Tool               | Description                                                                                                      |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `cognitive_store`  | Store a new fact. Supports `dryRun=true` to check for duplicates before writing.                                 |
+| `cognitive_recall` | Hybrid search facts. Query is optional (filter-only mode). Supports `modules[]` for multi-module parallel query. |
+| `cognitive_update` | Patch a fact in-place (confidence, tags, citations, module, type). Supports incremental `addTags`/`removeTags`.  |
+| `cognitive_forget` | Archive (soft-delete) a fact with a reason.                                                                      |
+
+### Search & Discovery
+
+| Tool                              | Description                                                                        |
+| --------------------------------- | ---------------------------------------------------------------------------------- |
+| `cognitive_search_documents`      | Hybrid search across indexed document chunks (DDD docs, architecture, guides).     |
+| `cognitive_search_code_artifacts` | Semantic search across indexed TypeScript code (entities, use cases, ports).       |
+| `cognitive_search_test_artifacts` | Semantic search across indexed tests (unit, integration, E2E).                     |
+| `cognitive_correlate`             | Cross-collection correlation: docs ↔ code ↔ tests. Gap detection & traceability. |
+
+### Indexing
+
+| Tool                            | Description                                                  |
+| ------------------------------- | ------------------------------------------------------------ |
+| `cognitive_store_document`      | Index a document chunk with checksum-based change detection. |
+| `cognitive_store_code_artifact` | Index a TypeScript code artifact with AST metadata.          |
+| `cognitive_store_test_artifact` | Index a test file with describe/it block metadata.           |
+
+### Analysis & Maintenance
+
+| Tool                 | Description                                                                                |
+| -------------------- | ------------------------------------------------------------------------------------------ |
+| `cognitive_reason`   | Synthesize a structured answer from facts — groups by module/type, detects contradictions. |
+| `cognitive_timeline` | Chronological view with date range filtering and daily grouping.                           |
+| `cognitive_stats`    | Quick dashboard: counts by type/module/status, top tags, recent activity.                  |
+| `cognitive_verify`   | Check if file:line citations still exist on disk.                                          |
+| `cognitive_audit`    | Full quality audit: stale facts, broken citations, duplicate candidates.                   |
+| `cognitive_compact`  | Find and merge duplicate facts (preview or execute mode).                                  |
+| `cognitive_health`   | Weaviate infrastructure health: version, nodes, collections, tenants.                      |
+
+---
+
+## Fact Types & Lifecycle
+
+| Type          | TTL           | Use for                                       |
+| ------------- | ------------- | --------------------------------------------- |
+| `invariant`   | ∞             | Permanent architecture rules. Confidence: 1.0 |
+| `policy`      | Until changed | Business decisions that may evolve            |
+| `convention`  | 6 months      | Team conventions, re-audit periodically       |
+| `observation` | 30 days       | Debugging insights, re-verify when recalled   |
+| `ephemeral`   | 7 days        | Temporary notes, auto-expire                  |
+
+---
+
+## Agent Profiles
+
+Profiles tune recall behavior per agent role. See [config/profiles.json](config/profiles.json) for a full example.
+
+```json
+{
+  "architect-agent": {
+    "name": "architect-agent",
+    "priorityTypes": ["invariant", "policy", "convention"],
+    "boostTags": ["architecture", "design"],
+    "suppressTags": ["test-only"],
+    "maxRecall": 10,
+    "alpha": 0.7
+  }
+}
+```
+
+**`alpha`** controls hybrid search balance: `0.0` = keyword-heavy (BM25), `1.0` = semantic-heavy (vector).
+
+Use `agent` parameter in `cognitive_recall` to activate a profile:
+
+```
+cognitive_recall({ query: "cross-BC rules", agent: "architect-agent" })
+```
+
+---
+
+## Pattern Detection (Git Hooks)
+
+Auto-detect conventions from git diffs. See [examples/patterns/](examples/patterns/) for pattern templates.
+
+```bash
+# Set up
+export COGNITIVE_PATTERNS_FILE=./.cognitive/patterns.ts
+
+# After each commit
+npx tsx ./node_modules/@porast1/mcp-cognitive/dist/hooks/post-commit.js
+```
+
+---
+
+## CLI Tools
+
+```bash
+npx mcp-cognitive-sync     # Sync markdown docs → knowledge base
+npx mcp-cognitive-audit    # Audit stale facts and broken citations
+npx mcp-cognitive-verify   # Verify citation file references
+npx mcp-cognitive-stale    # List stale facts that need re-verification
+```
+
+---
+
+## Development
+
+**Code Quality Tools:**
+
+```bash
+# ESLint — TypeScript linting (181 warnings tracked, 0 errors)
+pnpm lint              # Check for issues
+pnpm lint:fix          # Auto-fix where possible
+
+# Prettier — Code formatting
+pnpm format            # Format all files
+pnpm format:check      # Check formatting status
+
+# Tests
+pnpm test              # Run all 162 tests
+pnpm test:watch        # Watch mode for development
+
+# Build
+pnpm build             # Compile TypeScript → dist/
+```
+
+**Linting Rules:**
+
+- ✅ Basic: unused vars, explicit any, non-null assertions
+- ✅ Code style: prefer const, no var, template literals
+- ✅ Safety: no debugger, eqeqeq
+- ⚠️ Tests: relaxed rules (any allowed, console.log allowed)
+
+**Configuration:**
+
+- `eslint.config.mjs` — flat config with TypeScript parser
+- `.prettierrc` — single quotes, 100 print width, trailing commas
+- `.prettierignore` — excludes dist/, node_modules/, backups
+
+---
+
+## Testing
+
+**Test Tenant Isolation:** All integration tests use dedicated test tenants to prevent production data loss.
+
+```bash
+# First-time setup: Create test tenants in Weaviate
+cd weaviate-dev-stack
+./scripts/create-tenant.sh mcp-cognitive-test
+./scripts/create-tenant.sh test-isolation-a
+./scripts/create-tenant.sh test-isolation-b
+
+# Run tests (uses TEST_TENANT constants, never touches production data)
+pnpm test                  # 162 tests covering all 18 tools + Phase 8 features
+```
+
+**Test Coverage:**
+
+- ✅ CRUD operations: store, recall, update, archive (forget), verify
+- ✅ Search: hybrid (BM25 + vector), filters (type, module, tags, confidence)
+- ✅ Indexing: document sync, code artifacts, test artifacts
+- ✅ Analysis: stats, timeline, audit, health, correlate
+- ✅ Safety: archive/compact guards, decay tracking, citation validation
+- ✅ Phase 8: multi-module recall, optional query, dryRun mode
+- ✅ **Multi-tenant isolation: resetTenant, store UUID5, recall, archive** (4 tests)
+
+**Tenant Isolation Guarantees:**
+
+1. `resetTenant()` operates only on `this.tenantId` — other tenants remain untouched
+2. `COGNITIVE_ALLOW_RESET` global flag protects ALL tenants unless explicitly set
+3. Verified: reset tenant A → tenant B data survives (see [tenant-isolation.test.ts](tests/tenant-isolation.test.ts))
+4. Verified: UUID5 deterministic IDs work correctly across isolated tenants
+5. Verified: `recall()` queries never cross tenant boundaries
+6. Verified: `archive()` in one tenant does not affect facts in other tenants
+
+**Production Safety:** Test utilities in [tests/weaviate-test-utils.ts](tests/weaviate-test-utils.ts) enforce isolation via `TEST_TENANT` constant. Production tenant (e.g., `WEAVIATE_TENANT=diamondpage`) is never accessed during tests.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│  MCP Protocol (stdio)                        │
+├──────────────────────────────────────────────┤
+│  server.ts  — auto-registers 18 tools        │
+├──────────────────────────────────────────────┤
+│  tools/*.tool.ts  — Zod schema + execute fn  │
+├──────────────────────────────────────────────┤
+│  ports/cognitive-store.port.ts  — interface   │
+├──────────────────────────────────────────────┤
+│  adapters/weaviate-v3.adapter.ts  — impl      │
+│  (BM25 + vector + gRPC + multi-tenancy)      │
+└──────────────────────────────────────────────┘
+```
+
+**Collections:**
+
+- `CognitiveFact` — structured knowledge with confidence, citations, tags
+- `DocumentChunk` — markdown docs split by section
+- `CodeArtifact` — TypeScript files with AST metadata
+- `TestArtifact` — test files with describe/it block text
+
+---
+
+## Weaviate Infrastructure
+
+This package requires a running Weaviate instance with `text2vec-transformers` and `reranker-transformers` modules.
+
+**Recommended:** Use [weaviate-dev-stack](https://github.com/porast1/weaviate-dev-stack) — a pre-configured Docker Compose stack:
+
+```bash
+git clone https://github.com/porast1/weaviate-dev-stack
+cd weaviate-dev-stack
+docker-compose up -d
+```
+
+| Port    | Service           |
+| ------- | ----------------- |
+| `8200`  | Weaviate HTTP API |
+| `50052` | Weaviate gRPC     |
+
+Multi-tenancy is handled automatically. Each project gets its own tenant via `WEAVIATE_TENANT`.
+
+---
+
+## Project Setup Template
+
+Recommended structure in your project:
+
+```
+your-project/
+├── .cognitive/
+│   ├── profiles.json        # Agent profiles (from config/profiles.json)
+│   ├── patterns.ts          # Pattern definitions (optional, see examples/)
+│   └── pending-facts.json   # Auto-detected facts by post-commit hook (git-ignored)
+├── .vscode/
+│   └── mcp.json             # MCP server config (from config/mcp.jsonc)
+├── .env                     # Environment variables (from config/.env.example)
+└── .gitignore               # Add: .cognitive/pending-facts.json, .cognitive/facts.sqlite
+```
+
+See [`examples/`](examples/) for pattern & profile templates with detailed documentation.
+
+---
+
+## License
+
+MIT

package/config/.env.example

@@ -0,0 +1,21 @@
+# ─── MCP Cognitive Environment Variables ─────────────────────────────────────
+# Copy this file to your project root as .env and adjust values.
+# All variables are optional — defaults shown in comments.
+
+# ─── Weaviate Connection ─────────────────────────────────────────────────────
+WEAVIATE_URL=localhost:8200                  # Weaviate HTTP endpoint
+WEAVIATE_TENANT=myproject                    # Tenant name for data isolation (strongly recommended)
+# WEAVIATE_GRPC_PORT=50052                   # gRPC port override (default: auto-detected from WEAVIATE_URL)
+
+# ─── Workspace ───────────────────────────────────────────────────────────────
+# WORKSPACE_ROOT=/path/to/your/project      # Project root for resolving citation paths (default: cwd)
+# COGNITIVE_PROJECT=MyProject                # Project identifier for multi-project tagging (default: "default")
+
+# ─── Agent Configuration ─────────────────────────────────────────────────────
+# COGNITIVE_PROFILES_FILE=./.cognitive/profiles.json    # Agent profiles JSON for recall tuning
+# COGNITIVE_PATTERNS_FILE=./.cognitive/patterns.ts      # Pattern definitions for post-commit hook
+
+# ─── Safety Guards ───────────────────────────────────────────────────────────
+# COGNITIVE_MAX_ARCHIVES=20                  # Max archive operations per session (default: 20)
+# COGNITIVE_MAX_COMPACTS=10                  # Max compact operations per session (default: 10)
+# COGNITIVE_ALLOW_RESET=false                # Enable resetTenant() — TEST ENVIRONMENTS ONLY (default: false)

package/config/mcp.jsonc

@@ -0,0 +1,33 @@
+{
+  // MCP Cognitive Server — VS Code / Copilot configuration
+  //
+  // Copy this file to your project's .vscode/mcp.json (merge with existing if needed).
+  //
+  // Prerequisite: Weaviate must be running.
+  //   git clone https://github.com/porast1/weaviate-dev-stack && cd weaviate-dev-stack && docker-compose up -d
+  //
+  // Full docs: https://github.com/porast1/mcp-cognitive#readme
+  // All env vars: see config/.env.example
+
+  "servers": {
+    "cognitive": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["./node_modules/@porast1/mcp-cognitive/dist/server.js"],
+      "env": {
+        // ─── Required ──────────────────────────────────────────────
+        "WEAVIATE_URL": "localhost:8200",
+        "WEAVIATE_TENANT": "myproject",
+
+        // ─── Recommended ───────────────────────────────────────────
+        "WORKSPACE_ROOT": "${workspaceFolder}",
+        "COGNITIVE_PROFILES_FILE": "./.cognitive/profiles.json"
+
+        // ─── Optional (uncomment as needed) ────────────────────────
+        // "COGNITIVE_PROJECT": "MyProject",
+        // "WEAVIATE_GRPC_PORT": "50052",
+        // "COGNITIVE_PATTERNS_FILE": "./.cognitive/patterns.ts"
+      }
+    }
+  }
+}