@shahmilsaari/memory-core 1.0.22 → 1.0.26

package/README.md

@@ -1,923 +1,130 @@
 # memory-core
 
-**Every AI coding agent in your project, following your rules. Automatically.**
+> Universal AI memory for developers. Store architecture rules once — every AI coding agent reads them before writing code.
 
-You decide the architecture. memory-core remembers it. Every AI tool — Copilot, Cursor, Claude Code, Windsurf, and 10 more — reads those rules before writing a single line of code.
-
-Website: https://memory-core.shahmilsaari.my/
-
-```bash
-npx @shahmilsaari/memory-core init
-```
-
-Fully local or cloud — your choice. **v0.2.16**
-
----
-
-## What does it actually do?
-
-Without memory-core, every AI agent starts fresh. It doesn't know you're using Clean Architecture. It doesn't know controllers shouldn't call the database. It doesn't know why you made that decision six months ago.
-
-With memory-core:
-
-1. You run `init` once — it verifies your PostgreSQL and Ollama connections, picks your model, lets you choose which agents to generate files for, and installs a pre-commit hook
-2. Those agents read the files and follow your rules — automatically
-3. Watch mode catches violations as you type, not just at commit time
-4. When you commit, the hook checks your code before the commit goes through (advisory by default — logs violations but never blocks)
-
----
-
-## Before you start
-
-You need three things installed:
-
-| What | Why | Install |
-|---|---|---|
-| PostgreSQL 14+ | Stores your rules and decisions | See below |
-| pgvector | Makes search smart (finds similar rules, not just exact matches) | See below |
-| Ollama | Runs AI locally — no API key needed | See below |
-
----
-
-## Install
-
-### PostgreSQL
-
-**macOS**
-```bash
-brew install postgresql@16
-brew services start postgresql@16
-```
-
-**Linux**
-```bash
-sudo apt install postgresql postgresql-contrib
-sudo systemctl start postgresql
-```
-
-**Windows** — [download from postgresql.org](https://www.postgresql.org/download/windows/)
-
----
-
-### pgvector
-
-pgvector adds AI-powered search to PostgreSQL.
-
-**macOS + PostgreSQL 17+** (easiest)
-```bash
-brew install pgvector
-```
-
-**macOS + PostgreSQL 16** (brew's pgvector targets 17+, so build from source)
-```bash
-xcode-select --install
-git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git /tmp/pgvector
-cd /tmp/pgvector
-make PG_CONFIG=/opt/homebrew/opt/postgresql@16/bin/pg_config
-make install PG_CONFIG=/opt/homebrew/opt/postgresql@16/bin/pg_config
-```
-
-**Linux**
-```bash
-sudo apt install postgresql-16-pgvector   # replace 16 with your version
-```
-
-Check it worked:
-```bash
-psql -U $(whoami) -c "SELECT * FROM pg_available_extensions WHERE name = 'vector';"
-```
+[![npm](https://img.shields.io/npm/v/@shahmilsaari/memory-core)](https://www.npmjs.com/package/@shahmilsaari/memory-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 ---
 
-### Ollama
-
-Ollama runs AI models on your machine. Two models are needed — one for search, one for code checking.
-
-**macOS**
-```bash
-brew install ollama
-brew services start ollama
-```
-
-**Linux**
-```bash
-curl -fsSL https://ollama.com/install.sh | sh
-ollama serve &
-```
-
-**Windows** — [download from ollama.com](https://ollama.com/download)
-
-Pull the embedding model. The code-checking model is chosen during `init`:
-```bash
-ollama pull nomic-embed-text   # required for search
-ollama pull llama3.2           # or whichever model you plan to use
-```
+## What it does
 
----
+AI tools like Copilot, Cursor, and Claude Code start fresh every session. memory-core fixes that:
 
-### Create the database
+1. **Remember** — store architecture decisions and rules in PostgreSQL with reasons
+2. **Distribute** — generate instruction files for 14 AI agents from your stored rules
+3. **Enforce** — two-tier pipeline catches violations: deterministic layer graph (instant, confidence 1.0) then AI semantic review
 
 ```bash
-createdb memory_core
-psql -U $(whoami) -d memory_core -f setup.sql
-```
-
-`setup.sql`:
-```sql
-CREATE EXTENSION IF NOT EXISTS vector;
-
-CREATE TABLE IF NOT EXISTS memories (
-  id           BIGSERIAL PRIMARY KEY,
-  type         TEXT NOT NULL,
-  scope        TEXT NOT NULL DEFAULT 'project',
-  architecture TEXT,
-  project_name TEXT,
-  title        TEXT,
-  content      TEXT NOT NULL,
-  reason       TEXT,
-  context      JSONB NOT NULL DEFAULT '{}',
-  tags         TEXT[] DEFAULT '{}',
-  embedding    vector(768),
-  created_at   TIMESTAMP DEFAULT now()
-);
-
-CREATE INDEX IF NOT EXISTS memories_embedding_idx
-  ON memories USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
-CREATE INDEX IF NOT EXISTS memories_architecture_idx ON memories (architecture);
-CREATE INDEX IF NOT EXISTS memories_scope_idx ON memories (scope);
-
-CREATE TABLE IF NOT EXISTS graph_snapshots (
-  id          TEXT PRIMARY KEY,
-  root_path   TEXT NOT NULL,
-  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
-  nodes       JSONB NOT NULL DEFAULT '[]'::jsonb,
-  edges       JSONB NOT NULL DEFAULT '[]'::jsonb
-);
-
-CREATE INDEX IF NOT EXISTS graph_snapshots_root_path_idx ON graph_snapshots (root_path);
-CREATE INDEX IF NOT EXISTS graph_snapshots_created_at_idx ON graph_snapshots (created_at DESC);
+npx @shahmilsaari/memory-core init
 ```
 
----
-
 ## Quick start
 
 ```bash
-# 1. Go to your project
-cd my-api
-
-# 2. Initialize — verifies connections, picks your model, generates config files
+# 1. Initialize in your project
 npx @shahmilsaari/memory-core init
 
-# 3. Load 281 predefined best-practice rules
-npx @shahmilsaari/memory-core seed
-```
-
-That's it. Every AI agent in your project now has your rules.
-
----
-
-## Commands
-
-For the full CLI reference, examples, and command behavior notes, see [COMMANDS.md](./COMMANDS.md).
-
-New setup-management commands:
-- `memory-core status` — show project name, provider/model, agents, hook state, generated files, and health checks
-- `memory-core auto-sync` — show or change automatic agent file regeneration (`on`, `off`, or `status`)
-- `memory-core uninstall` — remove memory-core from the current project; use `reset` when you only need to regenerate files
-- `memory-core provider set <provider>` — switch code-checking provider without rerunning `init`
-- `memory-core model set <model>` — update chat or embedding model from the CLI
-- `memory-core model doctor` — verify database, Ollama, model installation, and cloud API key presence
-- `memory-core graph build|list|show|diff` — build, inspect, and compare dependency graph snapshots
-- `memory-core graph migrate` — create/update graph snapshot schema in PostgreSQL
-- `memory-core graph doctor` — verify graph backend health (PostgreSQL + file fallback)
-- `memory-core dashboard` — open the local Svelte command center with live WebSocket updates
-
-## User Documentation
-
-The public docs focus on how to install, use, configure, reset, and uninstall memory-core:
-
-- Website: https://memory-core.shahmilsaari.my/
-- Docs: https://memory-core.shahmilsaari.my/docs/
-- Quick start and installation: `website/docs/intro.md`, `website/docs/installation.md`
-- Daily usage: `website/docs/workflow.md`
-- CLI reference: `website/docs/commands.md`
-- Dashboard and model setup: `website/docs/dashboard.md`, `website/docs/models.md`
-- Reset and uninstall behavior: `website/docs/cleanup.md`
-- Architecture migration notes: `docs/migration-phase6-cutover.md`
-
-The static homepage remains `index.html` at `/`. Public docs are plain static HTML generated from the markdown files in `website/docs/` and served under `/docs/`.
-
-```bash
-npm run site:start   # build and preview the full site at / and /docs/
-npm run site:build   # assemble static output in site-build/
-npm run site:serve   # serve an existing site-build/ locally
-npm run docs:build   # build only the static docs app
-npm run docs:serve   # preview the existing site-build/ output
-```
+# 2. Load best-practice rules for your architecture
+memory-core seed --arch clean-architecture
 
-### `init` — Set up a project
+# 3. Store a project decision
+memory-core remember "No direct DB calls from controllers"
 
-```bash
-npx @shahmilsaari/memory-core init
+# 4. Enforce on every diff
+memory-core check --diff HEAD~1
 ```
 
-Walks you through:
-- PostgreSQL connection URL — **tested live, retries until connected**
-- Ollama URL — **tested live, retries until reachable** (used for embeddings)
-- Code-checking provider — **Ollama (local), OpenAI, Anthropic, or MiniMax**
-- Code-checking model — picked from a list, verified before continuing
-- Project name, type, architecture, language
-- Which agents to generate files for — **multi-select, all pre-checked, Space to deselect** — saved to `.memory-core.json`
-- Hook mode — **advisory** (logs violations, never blocks) or **strict** (blocks commits)
-- Whether to enable caveman mode (optional token saver)
-
-Generates config files for every selected AI agent, saves your choices to `.memory-core.json`, enables auto-sync by default, and automatically adds all generated files to `.gitignore` under a `# memory-core generated files` block.
-
-At the end, the banner shows live ✓/✗ status for PostgreSQL and Ollama so you know everything is working.
-
----
-
-### `sync` — Refresh all agent files
-
-Regenerate every agent file on demand. This still exists even though `remember`, `import`, `edit`, `remove`, `forget`, and `ignore` auto-sync by default after changing memories.
-
-```bash
-npx @shahmilsaari/memory-core sync
-```
+## Architecture enforcement
 
-Multi-selects which agents to sync (pre-checked from your `.memory-core.json` config). Skips files that haven't changed and reports how many were updated vs already up to date:
+The `check --diff` command runs a two-tier enforcement pipeline:
 
 ```
-  3 updated, 11 already up to date
+git diff → FileClassifier → ASTAnalyzer → GraphBuilder
+         → RuleMatcher → EvidencePacketBuilder
+         → graphEngine (full codebase graph)
+         → DeterministicValidator (confidence 1.0)
+         → AI judge (OllamaJudge / DeepSeek / OpenAI-compatible)
+         → ConfidenceGate → allow | warn | block
 ```
 
-Use `--no-sync` on memory-changing commands when you want to save database changes without regenerating files immediately.
+Configure your layers in `.archmind/layers.json` and rules in `.archmind/rules.json`. The dashboard shows a live layer graph SVG updated in real time as rules change.
 
-Manage the default:
+Built-in production hardening: rate limiter prevents concurrent AI calls, content-addressed cache skips redundant checks, auto graph build has a 15s timeout so hooks never hang, and all check results are logged as structured JSON to `.archmind/check.log`.
 
-```bash
-npx @shahmilsaari/memory-core auto-sync        # show current setting
-npx @shahmilsaari/memory-core auto-sync off    # save only, sync manually later
-npx @shahmilsaari/memory-core auto-sync on     # restore default behavior
-```
-
-Auto-sync failures are non-fatal. If regeneration cannot run, memory-core prints the reason and tells you to run `memory-core sync` manually.
-
----
-
-### `remember` — Save a decision
-
-Made a decision your team should never forget? Save it.
-
-```bash
-npx @shahmilsaari/memory-core remember "Controllers must never call the database directly"
-```
-
-It will ask you *why* — that reason gets stored alongside the rule and shown to AI agents and developers when a violation is caught.
+## Installation requirements
 
-With flags (skip the prompts):
-```bash
-npx @shahmilsaari/memory-core remember "Use DTOs for all API responses" \
-  --type rule \
-  --scope global \
-  --reason "Raw DB entities expose internal schema and sensitive fields" \
-  --applies-to "controllers,API responses" \
-  --avoid-when "internal domain transformations" \
-  --example "return UserResponseDto instead of UserEntity" \
-  --tags "api,dto"
-```
-
-| Flag | Options | Default |
+| Dependency | Purpose | Install |
 |---|---|---|
-| `--type` | `decision` `rule` `pattern` `note` | `decision` |
-| `--scope` | `global` `project` | `project` |
-| `--reason` | any text | asked interactively; fallback is stored if blank |
-| `--applies-to` | comma-separated use cases | none |
-| `--avoid-when` | comma-separated exceptions | none |
-| `--example` | comma-separated examples | none |
-| `--source` | source note, ticket, or review | none |
-| `--tags` | comma-separated | none |
-
-Structured context is stored in the database as JSON and rendered into generated agent files as `Why`, `Use when`, `Avoid when`, and `Examples`, which gives AI agents clearer guidance than a flat rule sentence.
-
----
-
-### `search` — Find a rule or decision
-
-```bash
-npx @shahmilsaari/memory-core search "error handling"
-npx @shahmilsaari/memory-core search "auth strategy" --limit 10
-```
-
-Uses AI search — finds related rules even if you don't use the exact words.
+| Node.js 18+ | Runtime | — |
+| PostgreSQL 14+ | Rules storage | `brew install postgresql@16` |
+| pgvector | Semantic search | `brew install pgvector` |
+| Ollama | Local embeddings | `ollama pull nomic-embed-text` |
 
----
-
-### `seed` — Load predefined rules
-
-281 best-practice rules across all supported architectures, each with a plain-English reason explaining why the rule exists.
-
-```bash
-npx @shahmilsaari/memory-core seed                              # all architectures
-npx @shahmilsaari/memory-core seed --arch clean-architecture   # one only
-npx @shahmilsaari/memory-core seed --force                     # re-seed existing
-```
-
----
-
-### `watch` — Catch violations as you type
-
-```bash
-npx @shahmilsaari/memory-core watch
-```
-
-Runs in the background and checks each file the moment you save it. You see violations immediately — before you even think about committing.
-
-```
-  archmind watch — real-time rule enforcement
-
-  watching: /your/project
-  model:    llama3.2
-  rules:    24
-  ctrl+c to stop
-
-  [10:42:11] saved: src/controllers/user.ts
+Cloud providers (OpenAI, Anthropic, DeepSeek, any OpenAI-compatible endpoint) can be used for code analysis — embeddings always stay local.
 
-  ✗ 1 violation in src/controllers/user.ts
-
-  [1] src/controllers/user.ts:34
-      Rule:   Thin controllers — business logic belongs in services
-      Why:    Logic in controllers cannot be reused from other entry points
-      Issue:  Password hashing inside the route handler
-      Fix:    Move to UserService.hashPassword()
-```
-
-Options:
-```bash
-npx @shahmilsaari/memory-core watch --path src/   # watch a specific folder only
-npx @shahmilsaari/memory-core watch --scan-on-start  # snapshot-scan tracked files once, then keep watching
-npx @shahmilsaari/memory-core watch --verbose     # show extra details
-npx @shahmilsaari/memory-core watch --debug       # show prompt, diff, and raw model output
-```
+## Supported AI agents
 
-Only checks source files — ignores `node_modules`, `dist`, config files, JSON, etc.  
-`--scan-on-start` is useful after a big refactor because it refreshes current live stats automatically before normal save-based watch mode begins.
+Claude Code · GitHub Copilot · Cursor · Windsurf · Cline · Roo Code · Aider · Continue.dev · Devin · Amazon Q · Gemini Code Assist · Zed AI · JetBrains AI · OpenHands
 
----
-
-### `dashboard` — Local command center
-
-```bash
-npx @shahmilsaari/memory-core dashboard
-npx @shahmilsaari/memory-core dashboard --port 5178
-npx @shahmilsaari/memory-core dashboard --path /absolute/path/to/project
-npx @shahmilsaari/memory-core dashboard --no-watch
-```
-
-Starts a local Svelte dashboard at `http://localhost:5178` by default. The dashboard includes:
-
-- WebSocket live feed for `watch` events
-- terminal-style violation details with file, line, rule, reason, issue, fix, and code context
-- PostgreSQL connection status, database name, host, and redacted URL
-- code-checking model status, resolved Ollama model, embedding model, and provider
-- architecture-aware rule browser filtered to the project initialized during `init`
-- stats for most violated rules and files
-- live reload for `.env`, `.memory-core.env`, `.memory-core.json`, and `.memory-core-stats.json`
-
-The WebSocket endpoint is local: `ws://localhost:5178/ws`. Runtime config changes are reloaded and pushed to the browser without restarting the dashboard after the dashboard process is running.
-When `--path` is provided, it must point to the project root (the directory containing `.memory-core.json`).
-
----
-
-### `check` — Manual check (for CI)
-
-```bash
-npx @shahmilsaari/memory-core check --staged              # check staged files
-npx @shahmilsaari/memory-core check --staged --fast       # deterministic-only staged check
-npx @shahmilsaari/memory-core check --staged --verbose    # with extra detail
-npx @shahmilsaari/memory-core check --staged --debug      # show prompt, diff, and raw model output
-npx @shahmilsaari/memory-core check --commit-msg          # check .git/COMMIT_EDITMSG
-npx @shahmilsaari/memory-core check --commit-msg <file>   # check a specific message file
-npx @shahmilsaari/memory-core check --ci                  # CI mode using memories.json
-npx @shahmilsaari/memory-core check --all                 # scan all tracked source files
-npx @shahmilsaari/memory-core check --all --path src/     # scan only tracked files under src/
-```
-
-`--staged` is the same path used by the pre-commit hook. Add `--fast` to skip AI and memory retrieval for a low-latency deterministic check. `--commit-msg` validates a commit message file against `commitRules` — this is called automatically by the `commit-msg` hook. `--ci` reads `memories.json` with no database or Ollama required. `--all` and `--ci` are mutually exclusive.
-
----
-
-### `hook install` — Install hooks
-
-```bash
-npx @shahmilsaari/memory-core hook install             # advisory mode (default)
-npx @shahmilsaari/memory-core hook install --advisory  # logs violations, never blocks
-npx @shahmilsaari/memory-core hook install --strict    # blocks commits on violations
-npx @shahmilsaari/memory-core hook install --fast      # deterministic-only hook
-```
-
-Installs **two** git hooks:
-- `.git/hooks/pre-commit` — checks staged code against architecture rules.
-- `.git/hooks/commit-msg` — checks commit messages against `commitRules` (see `commit-rules` command).
-
-**Advisory mode (default):** violations are logged but the commit always goes through.
-
-**Strict mode:** violations block the commit. You see exactly what's wrong:
-
-```
-  ✗ 2 rule violations found — commit blocked
-
-  [1] Thin controllers  ×2
-      src/controllers/user.ts:32   Password validation in route handler
-      src/controllers/auth.ts:18   DB query inside controller
-
-  [2] src/domain/user.entity.ts:5
-      Rule:   Domain has zero external imports
-      Issue:  Imports 'typeorm' directly
-      Fix:    Define IUserRepository interface in domain/
-
-  To bypass: MEMORY_CORE_SKIP_HOOK=1 git commit
-  Manage rules: memory-core commit-rules --list
-```
-
-```bash
-npx @shahmilsaari/memory-core hook uninstall   # remove both hooks
-```
-
----
-
-### `list` — List memories from the database
-
-```bash
-npx @shahmilsaari/memory-core list
-```
-
-By default, shows memories relevant to the current project context: detected stack, current project name, plus shared/global memories. Use `--all` for the old database-wide view.
-
-```bash
-npx @shahmilsaari/memory-core list --all
-npx @shahmilsaari/memory-core list --type rule
-npx @shahmilsaari/memory-core list --scope global
-npx @shahmilsaari/memory-core list --arch clean-architecture
-npx @shahmilsaari/memory-core list --project my-api
-npx @shahmilsaari/memory-core list --limit 50
-```
+## Key commands
 
-| Flag | What it does |
+| Command | Description |
 |---|---|
-| `--type <type>` | Filter by type: `decision` `rule` `pattern` `note` |
-| `--scope <scope>` | Filter by scope: `global` `project` |
-| `--arch <architecture>` | Filter by architecture profile |
-| `--project <name>` | Filter by project name |
-| `--all` | Show the full shared database |
-| `--current` | Explicitly use the current project context |
-| `--limit <n>` | Max results (default 200) |
+| `memory-core init` | Set up memory-core in the current project |
+| `memory-core remember "..."` | Store an architecture decision |
+| `memory-core check --diff <ref>` | Evidence-based arch enforcement against a git ref |
+| `memory-core check --staged` | Check staged diff (pre-commit hook path) |
+| `memory-core watch --auto-fix` | Real-time violation detection with AI auto-fix |
+| `memory-core dashboard` | Live command center at `localhost:5178` |
+| `memory-core graph build` | Snapshot full codebase dependency graph |
+| `memory-core seed` | Load 281 best-practice rules |
+| `memory-core sync` | Regenerate all agent instruction files |
+| `memory-core export` | Export rules to `memories.json` for team sharing |
 
----
-
-### `remove` — Delete a memory
-
-```bash
-npx @shahmilsaari/memory-core remove <id>
-npx @shahmilsaari/memory-core remove <id> --no-sync
-```
-
-Deletes a memory by its ID. Get the ID from `list` or `search`.
-
----
-
-### `forget` — Bulk-delete memories
-
-```bash
-npx @shahmilsaari/memory-core forget --tag nextjs --scope global
-npx @shahmilsaari/memory-core forget --type ignore
-npx @shahmilsaari/memory-core forget --arch nuxt
-```
-
-Deletes memories by filter. At least one filter is required, so an empty `forget` command cannot wipe the database by accident.
-
-| Flag | What it does |
-|---|---|
-| `--tag <tag>` | Delete memories with a tag |
-| `--scope <scope>` | Filter by scope: `global` `project` |
-| `--type <type>` | Filter by type |
-| `--arch <architecture>` | Filter by architecture profile |
-| `--no-sync` | Skip automatic agent file regeneration |
-
----
-
-### `edit` — Edit a memory
-
-```bash
-npx @shahmilsaari/memory-core edit <id>
-npx @shahmilsaari/memory-core edit <id> --no-sync
-```
-
-Opens the memory interactively so you can update its content, reason, structured context, tags, type, or scope.
-
----
-
-### `export` — Export memories to a file
-
-```bash
-npx @shahmilsaari/memory-core export
-npx @shahmilsaari/memory-core export --output path/to/my-rules.json
-```
-
-Exports all memories from the database to `memories.json` in the project root (or the path you specify). Makes your rules portable and version-controllable — commit the file alongside your code.
-
----
-
-### `import` — Import memories from a file
-
-```bash
-npx @shahmilsaari/memory-core import
-npx @shahmilsaari/memory-core import --file path/to/my-rules.json
-npx @shahmilsaari/memory-core import --url https://example.com/team-rules.json
-npx @shahmilsaari/memory-core import --no-sync
-```
-
-Imports memories into the local database. Skips duplicates by content hash — safe to run more than once.
-
-| Flag | What it does |
-|---|---|
-| `--file <path>` | Import from a custom local file path |
-| `--url <url>` | Import from a remote URL |
-| `--no-sync` | Skip automatic agent file regeneration |
-
----
-
-### `ignore` — Mark false positives
-
-```bash
-npx @shahmilsaari/memory-core ignore "controllers may import prisma directly in migration scripts"
-```
-
-Saves a pattern so the hook and watcher never flag it again. Useful for intentional exceptions to a rule.
-
-```bash
-npx @shahmilsaari/memory-core ignore --list          # show all saved ignore patterns
-npx @shahmilsaari/memory-core ignore --remove <id>   # delete an ignore pattern
-npx @shahmilsaari/memory-core ignore "..." --no-sync # save without regenerating agent files
-```
-
----
-
-### `allow` — Allow intentional project patterns
-
-```bash
-npx @shahmilsaari/memory-core allow "generated by sqlc"
-npx @shahmilsaari/memory-core allow --list
-npx @shahmilsaari/memory-core allow --remove "generated by sqlc"
-```
-
-Stores lightweight per-project allowlist strings in `.memory-core.json`. Hook and watch checks treat these patterns as intentional before surfacing violations.
-
----
-
-### `commit-rules` — Enforce commit message format
-
-```bash
-npx @shahmilsaari/memory-core commit-rules "^(feat|fix|chore)" --message "Use conventional commits"
-npx @shahmilsaari/memory-core commit-rules "^WIP" --message "Don't commit WIP" --negate
-npx @shahmilsaari/memory-core commit-rules "PROJ-\d+" --message "Reference a JIRA ticket" --advisory
-npx @shahmilsaari/memory-core commit-rules --list
-npx @shahmilsaari/memory-core commit-rules --remove "^WIP"
-```
-
-Stores regex-based rules in `.memory-core.json` under `commitRules`. The `commit-msg` git hook (installed by `hook install`) validates every commit message against these rules before the commit is accepted.
-
-| Flag | What it does |
-|---|---|
-| `--message <msg>` | Required. Error message shown on violation. |
-| `--negate` | Pattern must NOT match (default: must match) |
-| `--advisory` | Warn only — do not block the commit |
-| `--list` | Show all saved commit rules |
-| `--remove <pattern>` | Remove a rule by pattern |
-
----
-
-### `ci-setup` — GitHub Actions integration
-
-```bash
-npx @shahmilsaari/memory-core ci-setup
-```
-
-Generates `.github/workflows/memory-core.yml`. Adds a PR check that runs `npx @shahmilsaari/memory-core check --ci`, using `memories.json` so CI can enforce architecture rules without a project-local database.
-
----
-
-### `stats` — Violation counters
-
-```bash
-npx @shahmilsaari/memory-core stats
-npx @shahmilsaari/memory-core stats --tune
-npx @shahmilsaari/memory-core stats --reset
-```
-
-Shows which rules fire most often and which files have the most violations. Each rule shows hit count and false-positive rate where available.
-
-- `--tune` shows only noisy rules (>40% false-positive rate) with their exact disable commands.
-- `--reset` clears all counters and recent violation history.
-- Live watch-state counters are shown when available.
-
----
-
-### `tune` — Silence noisy rules
-
-```bash
-npx @shahmilsaari/memory-core tune
-npx @shahmilsaari/memory-core tune --threshold 30
-npx @shahmilsaari/memory-core tune --yes
-```
-
-Interactively reviews rules with a high false-positive rate and adds them to `allowPatterns` in `.memory-core.json`.
-
-| Flag | What it does |
-|---|---|
-| `--threshold <n>` | False-positive % cutoff (default `40`) |
-| `--min-count <n>` | Minimum hits required (default `5`) |
-| `--yes` | Silence all qualifying rules without prompting |
-
----
-
-### `reset` vs `uninstall` — Cleanup commands
-
-Use `reset` when you want to keep using memory-core but need to regenerate or reinitialize project files. Use `uninstall` when you want memory-core removed from the current project.
-
-| Command | User intent | What it removes | Database |
-|---|---|---|---|
-| `reset --soft` | Regenerate agent files from a clean slate | Generated agent files only | Kept |
-| `reset` | Reinitialize memory-core in this project | Generated agent files, `.memory-core.json`, hook | Kept |
-| `reset --db` | Reinitialize and clear stored memories | Same as `reset` | Drops `memories` after confirmation |
-| `uninstall` | Remove memory-core from this project | Generated files, config/env/state, CI workflow, hook, `.gitignore` block | Kept |
-| `uninstall --db` | Remove project footprint and stored memory table | Same as `uninstall` | Drops `memories` after confirmation |
-
-### `reset` — Reinitialize generated files
-
-```bash
-npx @shahmilsaari/memory-core reset              # remove generated files + .memory-core.json + hook
-npx @shahmilsaari/memory-core reset --soft       # keep config and DB, remove only generated files
-npx @shahmilsaari/memory-core reset --db         # also drop the memories table from the database
-```
-
-Use this when memory-core should stay part of the project, but generated files need to be rebuilt or the project config should be recreated. Use `--soft` for the safest regeneration path.
+See [COMMANDS.md](COMMANDS.md) for the full reference.
 
-### `uninstall` — Remove memory-core from a project
+## Dashboard
 
 ```bash
-npx @shahmilsaari/memory-core uninstall          # remove generated files, config, env, hook, stats, and gitignore block
-npx @shahmilsaari/memory-core uninstall --db     # also drop the memories table after confirmation
+memory-core dashboard
 ```
 
-Use this when you want the project back to a pre-memory-core state. Database deletion is opt-in and only happens with `--db`.
-
----
-
-### `global` — Apply rules to every project
-
-```bash
-npx @shahmilsaari/memory-core global
-```
-
-Writes your rules to the global config of each AI agent — so they follow your rules in every project on your machine, not just the current one.
-
-| Agent | Where it writes |
-|---|---|
-| Claude Code | `~/.claude/CLAUDE.md` |
-| GitHub Copilot | VS Code `settings.json` |
-| Cursor | `~/.cursor/rules/memory-core.mdc` |
-| Cline | VS Code `settings.json` |
-| Continue.dev | `~/.continue/config.json` |
-| Aider | `~/.aider.conf.yml` |
-| Zed AI | `~/.config/zed/settings.json` |
-| Windsurf | `~/.windsurf/rules/memory-core.md` |
-
----
-
-## Supported agents
-
-| Agent | File generated |
-|---|---|
-| Claude Code | `CLAUDE.md` |
-| GitHub Copilot | `.github/copilot-instructions.md` |
-| Cursor | `.cursorrules` + `.cursor/rules/memory-core.mdc` |
-| Windsurf | `.windsurfrules` |
-| Cline | `.clinerules` |
-| Roo Code | `.roo/rules/memory-core.md` |
-| Aider | `.aider.conf.yml` |
-| Continue.dev | `.continue/config.json` |
-| Devin | `DEVIN.md` |
-| Amazon Q | `.amazonq/dev/guidelines.md` |
-| Gemini Code Assist | `.gemini/styleguide.md` |
-| Zed AI | `.zed/settings.json` |
-| JetBrains AI | `.idea/ai-instructions.md` |
-| OpenHands | `AGENTS.md` |
-
-Plus shared files: `AI_RULES.md`, `ARCHITECTURE.md`, `PROJECT_MEMORY.md`
-
----
-
-## Architecture profiles
-
-Pick the one that matches how your project is structured.
-
-**Backend**
-| Profile | Use when… |
-|---|---|
-| Clean Architecture | You want strict separation between domain, application, and infrastructure |
-| Modular Monolith | You're building feature modules that might become microservices later |
-| MVC | Standard web app with controllers and services |
-| Hexagonal | You want ports and adapters for maximum testability |
-| Go REST API | Go backend API with idiomatic error handling and clean package structure |
-| Laravel | Laravel with service-repository pattern |
-| NestJS | Modules, guards, pipes, DTOs, repository pattern |
-
-**Frontend**
-| Profile | Use when… |
-|---|---|
-| React | Functional components, hooks, React Query, Zustand |
-| Vue 3 | Composition API, Pinia, composables |
-| Angular | Standalone components, signals, OnPush strategy |
-| Svelte | Svelte 5 runes, SvelteKit load functions, snippets |
-| Nuxt 3 | Fullstack Vue with SSR |
-| React Native | Mobile apps |
-
-Fullstack projects get both sections in every generated file.
-
----
-
-## Caveman mode (optional)
-
-Cuts AI response length by 65–75% by removing filler words. Opt in during `init`.
-
-| Level | What it does |
-|---|---|
-| `lite` | Professional and concise |
-| `full` | Caveman-style short answers |
-| `ultra` | Absolute minimum words |
-
----
-
-## Day-to-day workflow
-
-```bash
-# Starting a new project
-cd my-api
-npx @shahmilsaari/memory-core init   # verifies connections, picks model, selects agents, installs hook
-npx @shahmilsaari/memory-core seed   # load 281 best-practice rules
+Opens at `http://localhost:5178`. Shows:
+- Live violations feed via WebSocket
+- Layer graph — interactive SVG of your architecture topology
+- Model switcher — change provider/model without restart
+- Token usage — Ollama shows "LOCAL (FREE)", paid providers show real counts
+- Actions panel — Sync Agents, Check All without opening a terminal
 
-# Made an architectural decision? Save it.
-npx @shahmilsaari/memory-core remember "All auth goes through middleware, never in controllers" \
-  --type decision --scope global
+## Environment
 
-# Optional: refresh agent files manually anytime
-npx @shahmilsaari/memory-core sync
+```env
+# PostgreSQL
+DATABASE_URL=postgres://localhost:5432/memory_core
 
-# Not sure how something was decided? Search.
-npx @shahmilsaari/memory-core search "caching strategy"
+# Ollama (local, for embeddings)
+OLLAMA_URL=http://localhost:11434
+OLLAMA_MODEL=nomic-embed-text
 
-# Inspect current setup, provider, model, and health checks
-npx @shahmilsaari/memory-core status
+# AI provider for code analysis (choose one)
+CHAT_PROVIDER=ollama
+CHAT_MODEL=qwen2.5-coder:7b
 
-# Open the local command center with live watch/config updates
-npx @shahmilsaari/memory-core dashboard
-
-# Switch code-checking provider or model without rerunning init
-npx @shahmilsaari/memory-core provider set openai --model gpt-4o-mini --api-key $OPENAI_API_KEY
-npx @shahmilsaari/memory-core model set qwen2.5-coder --provider ollama
-
-# See what rules are saved
-npx @shahmilsaari/memory-core list --type rule
-
-# Export rules to version control
-npx @shahmilsaari/memory-core export
-
-# Commit code → hook checks it automatically before committing
-git commit -m "add user endpoint"
-```
-
----
-
-## Environment variables
-
-memory-core creates `.memory-core.env` automatically during `init`. You can also set these manually:
-
-| Variable | Required | Default | What it does |
-|---|---|---|---|
-| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
-| `OLLAMA_URL` | No | `http://localhost:11434` | Where Ollama is running (used for embeddings) |
-| `OLLAMA_MODEL` | No | `nomic-embed-text` | Model used for search (embeddings) — always Ollama |
-| `CHAT_PROVIDER` | No | `ollama` | Provider for code checking: `ollama`, `openai`, `anthropic`, `minimax` |
-| `CHAT_MODEL` | No | `llama3.2` | Model used for code checking — chosen during `init` |
-| `CHAT_API_KEY` | No | — | API key for OpenAI / Anthropic / MiniMax (not needed for Ollama) |
-| `OLLAMA_CHAT_MODEL` | No | `llama3.2` | Legacy alias for `CHAT_MODEL` when provider is `ollama` |
-
----
-
-## Troubleshooting
-
-**`extension "vector" is not available`**
-pgvector isn't installed for your PostgreSQL version. Follow the [pgvector install steps](#pgvector) above.
-
-**`Ollama not running — skipping rule check`**
-Start Ollama: `brew services start ollama` (macOS) or `ollama serve` (Linux).
-
-**`Chat model "llama3.2" not found`**
-Run `ollama pull llama3.2`. Or switch provider/model with `npx @shahmilsaari/memory-core provider set ...` or `npx @shahmilsaari/memory-core model set ...`.
-
-**Using an API key instead of Ollama for code checking**
-During `init` choose OpenAI, Anthropic, or MiniMax when prompted for the check provider. Or switch later:
-```bash
-npx @shahmilsaari/memory-core provider set openai --model gpt-4o --api-key sk-...
-```
-
-Equivalent manual `.memory-core.env` settings:
-```
-CHAT_PROVIDER=openai
-CHAT_MODEL=gpt-4o
+# OpenAI-compatible (e.g. DeepSeek)
+CHAT_PROVIDER=openai-compatible
+CHAT_BASE_URL=https://api.deepseek.com/v1
+CHAT_MODEL=deepseek-chat
 CHAT_API_KEY=sk-...
 ```
-Embeddings always use Ollama (`nomic-embed-text`) regardless of provider.
-
-**`DATABASE_URL is not set`**
-Run `npx @shahmilsaari/memory-core init` — it will create the `.memory-core.env` file for you.
 
-**Not sure what memory-core is configured to use**
-Run `npx @shahmilsaari/memory-core status`.
+## Docs
 
-**Need to verify the model/database setup**
-Run `npx @shahmilsaari/memory-core model doctor`.
-
-**`createdb: role does not exist`**
-```bash
-createuser -s $(whoami)
-```
-
-**Hook is flagging JSON or config files**
-It won't — the hook only checks source code files: `.ts .tsx .js .jsx .py .php .rb .go .java .cs .swift .kt .rs .vue .svelte`. Everything else is skipped automatically.
-
-**Hook is flagging something that's intentional**
-Save an ignore pattern: `npx @shahmilsaari/memory-core ignore "your exception here"`. The hook and watcher will never flag it again.
-
----
-
-## Release checks
-
-Before publishing, run the same checks as CI:
-
-```bash
-npm run lint
-npm run typecheck
-npm test
-npm run build
-npm run smoke:pack
-npm run smoke:npx
-```
-
-`smoke:pack` verifies the npm tarball includes the built CLI plus templates/profiles.
-`smoke:npx` installs that tarball into a fresh temporary project and runs `npx --no-install memory-core init --quick`.
-
----
-
-## Roadmap
-
-| | Feature |
-|---|---|
-| ✓ | Watch mode — real-time violation alerts on save |
-| ✓ | Model picker — choose your Ollama model during init |
-| ✓ | Connection validation — PostgreSQL and Ollama verified during setup |
-| ✓ | Svelte 5 / SvelteKit profile and 37 rules |
-| ✓ | NestJS profile and 39 rules |
-| ✓ | Hook auto-prompt — hook mode offered during init, no separate step needed |
-| ✓ | CI/CD — `ci-setup` generates GitHub Actions workflow for PR enforcement |
-| ✓ | Agent selection — choose which agents to generate files for during init |
-| ✓ | Auto-sync — memory-changing commands refresh selected agent files by default |
-| ✓ | Export / import — portable memories.json for version control and team sharing |
-| ✓ | List / remove / edit — full CRUD for stored memories |
-| ✓ | False positive tagging — `ignore` and `allow` save exceptions for hook and watcher |
-| ✓ | Cleanup commands — `reset` regenerates/reinitializes files; `uninstall` removes memory-core |
-| ✓ | Test suite — 94 tests using Node.js built-in `node:test` |
-| ✓ | Multi-provider code checking — Ollama, OpenAI, Anthropic, MiniMax |
-| ✓ | Context-aware retrieval — surface the most relevant rules for the file being edited |
-| ✓ | Setup management — `status`, `provider set`, `model set`, `model doctor` |
-| ✓ | `--debug` flag — verbose output for diagnosing hook and watcher issues |
-| ✓ | Local Svelte dashboard — WebSocket live feed, runtime status, stats, and rules browser |
-| ✓ | Rule cache — 5-min TTL cache, invalidated by config or DB version change |
-| ✓ | Batch suppression — same rule ≥3× on same file auto-suppressed with a notice |
-| ✓ | False-positive tracking — `{ count, falsePositives }` stored per rule in stats |
-| ✓ | Violation clustering — violations grouped by rule, compact multi-location display |
-| ✓ | Auto-tuning — `memory-core tune` silences noisy rules interactively |
-| ✓ | Commit message linting — `commit-rules` + `commit-msg` git hook |
-| | Model guidance during init — recommend a model based on machine specs |
-| | Violation → rule pipeline — auto-suggest a new rule when the same violation repeats |
-| | Team sync — shared database so the whole team works from the same rule set |
-
----
+- [Commands reference](COMMANDS.md)
+- [Dashboard](docs/dashboard.md)
+- [Technical design](TECHNICAL_DESIGN.md)
+- [Website](https://shahmilsaari.github.io/memory-core/)
 
 ## License
 
 MIT
-
-*Built by [Shahmil Saari](https://github.com/shahmilsaari)*