@shahmilsaari/memory-core 1.0.25 → 1.0.26

package/README.md

@@ -1,714 +1,130 @@
 # memory-core
 
-**Your architecture rules, in every AI coding agent. Automatically.**
+> Universal AI memory for developers. Store architecture rules once — every AI coding agent reads them before writing code.
 
-AI agents like Copilot, Cursor, Claude Code, and Windsurf are powerful — but they start fresh every session. They don't know you're using Clean Architecture. They don't know controllers shouldn't call the database. They don't remember why you made that decision six months ago.
-
-memory-core fixes that. You save your architecture rules once. Every AI tool reads them before writing code. Violations get caught before they reach your repo.
-
-Website: https://memory-core.shahmilsaari.my/
-
-```bash
-npx @shahmilsaari/memory-core init
-```
-
-Fully local or cloud AI — your choice.
-
----
-
-## How it works
-
-memory-core has three jobs:
-
-**1. Remember** — Store your architecture decisions, rules, and patterns in a local PostgreSQL database with AI-powered search. When you decide "no direct DB calls from controllers", you save that rule with a reason. It's stored forever.
-
-**2. Distribute** — Generate instruction files for 14 AI agents (Cursor, Claude Code, Copilot, Windsurf, etc.) from your stored rules. Every agent reads your rules before it writes code.
-
-**3. Enforce** — Three-layer rule checking catches violations automatically:
-- **Deterministic** — string matching against known bad patterns (instant, no AI needed)
-- **Structural** — import graph analysis to catch architectural boundary violations
-- **AI semantic** — LLM reads the actual code diff against your rules
-
-You can run enforcement in watch mode (checks as you type), as a pre-commit hook (checks before each commit), or in CI (checks on every PR).
-
----
-
-## What's new in this version
-
-- **AI auto-fix** — When watch mode detects a violation, it can rewrite the file automatically and save the fix as a new rule
-- **Dry-run mode** — Run the full check pipeline without blocking commits: `check --dry-run`
-- **Schema alignment rules** — Define TypeScript↔Go struct pairs; catch field drift automatically: `schema add --ts --go`
-- **Bypass tracking** — Every `MEMORY_CORE_SKIP_HOOK=1` bypass is counted; re-prompted if no reason given
-- **Model switcher in dashboard** — Change provider and model from the UI without restarting
-- **Token usage display** — See AI call counts and token usage; Ollama shows "LOCAL (FREE)"
-- **Actions panel** — Trigger Sync Agents, Check All, and Tune Rules directly from the dashboard
+[![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)
 
 ---
 
-## Before you start
+## What it does
 
-You need three things:
+AI tools like Copilot, Cursor, and Claude Code start fresh every session. memory-core fixes that:
 
-| What | Why | Install |
-|---|---|---|
-| PostgreSQL 14+ | Stores your rules and decisions | See below |
-| pgvector | Enables AI-powered rule search | See below |
-| Ollama | Runs AI locally — no API key needed | See below |
+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
 
-Cloud providers (OpenAI, Anthropic, MiniMax) are also supported if you prefer not to run Ollama locally.
-
----
-
-## 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 similarity search to PostgreSQL, so memory-core can find rules related to your query even when you don't use the exact words.
-
-**macOS + PostgreSQL 17+**
-```bash
-brew install pgvector
-```
-
-**macOS + PostgreSQL 16** (brew 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
-```
-
-Verify:
-```bash
-psql -U $(whoami) -c "SELECT * FROM pg_available_extensions WHERE name = 'vector';"
-```
-
----
-
-### Ollama
-
-Ollama runs AI models on your machine. Two models are used: one for search (embeddings) and 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 required models:
-```bash
-ollama pull nomic-embed-text   # required for search (always Ollama)
-ollama pull llama3.2           # or whichever model you plan to use for code checking
-```
-
----
-
-### Create the database
-
-```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);
-```
-
----
-
-## Quick start
-
-```bash
-# 1. Go to your project
-cd my-api
-
-# 2. Initialize — verifies connections, picks your model, generates config files
 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.
-
----
-
-## Day-to-day workflow
-
-```bash
-# Made an architectural decision? Save it.
-npx @shahmilsaari/memory-core remember "Controllers must never call the database directly" \
-  --type rule --reason "Keeps HTTP concerns out of application logic"
-
-# Watch mode — catch violations the moment you save a file
-npx @shahmilsaari/memory-core watch
-
-# AI auto-fix — let the AI rewrite violations automatically
-npx @shahmilsaari/memory-core watch --auto-fix
-
-# See the dashboard — live violations, model status, token usage, actions
-npx @shahmilsaari/memory-core dashboard
-
-# Manual check before a commit
-npx @shahmilsaari/memory-core check --staged
-
-# Dry run — see what would be flagged without blocking
-npx @shahmilsaari/memory-core check --staged --dry-run
-
-# Not sure how something was decided? Search.
-npx @shahmilsaari/memory-core search "caching strategy"
-
-# See what's saved
-npx @shahmilsaari/memory-core list --type rule
-
-# Export rules for version control and team sharing
-npx @shahmilsaari/memory-core export
-```
-
----
-
-## Commands
-
-### `init` — Set up a project
+## Quick start
 
 ```bash
+# 1. Initialize in your project
 npx @shahmilsaari/memory-core init
-```
-
-Walks you through:
-- PostgreSQL connection URL — **tested live, retries until connected**
-- Ollama URL — **tested live, retries until reachable**
-- 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
-- Hook mode — **advisory** (logs violations, never blocks) or **strict** (blocks commits)
-- Whether to enable caveman mode
-
-Generates config files for every selected agent, installs the pre-commit hook, and auto-syncs by default.
-
----
-
-### `sync` — Refresh all agent files
-
-```bash
-npx @shahmilsaari/memory-core sync
-```
-
-Regenerates every agent instruction file from your current rules. Reports updated vs already up to date:
-
-```
-  3 updated, 11 already up to date
-```
-
-Turn off auto-sync when you want to batch memory edits, then sync once:
-```bash
-npx @shahmilsaari/memory-core auto-sync off
-npx @shahmilsaari/memory-core auto-sync on
-```
-
----
-
-### `remember` — Save a decision
-
-```bash
-npx @shahmilsaari/memory-core remember "Controllers must never call the database directly"
-```
-
-It will ask you *why* — the reason gets stored alongside the rule and shown when a violation is caught.
-
-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 |
-|---|---|---|
-| `--type` | `decision` `rule` `pattern` `note` | `decision` |
-| `--scope` | `global` `project` | `project` |
-| `--reason` | any text | asked interactively |
-| `--applies-to` | comma-separated use cases | none |
-| `--avoid-when` | comma-separated exceptions | none |
-| `--example` | comma-separated examples | none |
-| `--tags` | comma-separated | none |
-
----
-
-### `watch` — Catch violations as you type
-
-```bash
-npx @shahmilsaari/memory-core watch
-npx @shahmilsaari/memory-core watch --auto-fix   # let AI rewrite violations automatically
-npx @shahmilsaari/memory-core watch --path src/  # watch a specific folder only
-npx @shahmilsaari/memory-core watch --scan-on-start  # scan all tracked files once, then watch
-npx @shahmilsaari/memory-core watch --verbose
-npx @shahmilsaari/memory-core watch --debug
-```
-
-Runs in the background and checks each file the moment you save it. Violations appear immediately:
-
-```
-  [10:42:11] saved: src/controllers/user.ts
-
-  ✗ 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()
-```
-
-With `--auto-fix`, when a violation is detected the AI rewrites the file and saves the fix as a new rule so the same mistake doesn't repeat.
-
----
-
-### `check` — Manual check
-
-```bash
-npx @shahmilsaari/memory-core check --staged              # check staged files (same as hook)
-npx @shahmilsaari/memory-core check --staged --dry-run   # show results without blocking
-npx @shahmilsaari/memory-core check --staged --fast      # deterministic-only, no AI
-npx @shahmilsaari/memory-core check --file src/user.ts   # check a single file
-npx @shahmilsaari/memory-core check --all                 # scan all tracked source files
-npx @shahmilsaari/memory-core check --commit-msg          # check .git/COMMIT_EDITMSG
-npx @shahmilsaari/memory-core check --ci                  # CI mode using memories.json
-```
-
-`--dry-run` runs the full check pipeline but exits 0, so CI or pre-commit can report violations without blocking. `--fast` skips AI for a low-latency check. `--file` checks a single file retroactively (treats entire file content as the diff).
-
----
-
-### `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`. What you get:
-
-- **Live violations feed** — WebSocket push, no polling
-- **Model switcher** — change provider and model from the UI; takes effect immediately
-- **Token usage** — AI call count and tokens used; Ollama shows "LOCAL (FREE)"
-- **Actions panel** — Sync Agents, Check All, Tune Rules without touching the terminal
-- **PostgreSQL health** — connection status, database name, host
-- **Rule browser** — filtered to your project's architecture profile
-- **Stats** — most violated rules and files
+# 2. Load best-practice rules for your architecture
+memory-core seed --arch clean-architecture
 
----
-
-### `schema` — TypeScript ↔ Go struct alignment
-
-Catch field drift between TypeScript interfaces and Go structs automatically.
-
-```bash
-# Define a pair to track
-npx @shahmilsaari/memory-core schema add \
-  --ts src/types/user.ts \
-  --go internal/models/user.go
+# 3. Store a project decision
+memory-core remember "No direct DB calls from controllers"
 
-# List tracked pairs
-npx @shahmilsaari/memory-core schema list
-
-# Check all pairs for field drift
-npx @shahmilsaari/memory-core schema check
+# 4. Enforce on every diff
+memory-core check --diff HEAD~1
 ```
 
-When a field is added to one side but not the other, `schema check` reports it as a violation.
-
----
+## Architecture enforcement
 
-### `hook install` — Install pre-commit and commit-msg hooks
+The `check --diff` command runs a two-tier enforcement pipeline:
 
-```bash
-npx @shahmilsaari/memory-core hook install             # advisory mode (default)
-npx @shahmilsaari/memory-core hook install --strict    # block commits on violations
-npx @shahmilsaari/memory-core hook install --fast      # deterministic-only check
-npx @shahmilsaari/memory-core hook uninstall
 ```
-
-**Advisory mode (default):** violations are logged but the commit always goes through.
-
-**Strict mode:** violations block the commit. You see exactly what's wrong and how to fix it.
-
-To bypass strict mode in an emergency:
-```bash
-MEMORY_CORE_SKIP_HOOK=1 git commit -m "..."
+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
 ```
 
-Every bypass is tracked. If you don't provide a reason, memory-core will ask you on the next commit.
+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.
 
----
-
-### `search` — Find a rule
+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 search "error handling"
-npx @shahmilsaari/memory-core search "auth strategy" --limit 10
-```
+## Installation requirements
 
-Uses AI search — finds related rules even if you don't use the exact words.
-
----
-
-### `seed` — Load predefined rules
-
-281 best-practice rules across all supported architectures, each with a plain-English reason.
-
-```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
-```
-
----
-
-### `list`, `remove`, `edit` — Manage your rules
-
-```bash
-npx @shahmilsaari/memory-core list
-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 remove <id>
-npx @shahmilsaari/memory-core edit <id>
-```
-
----
-
-### `export` / `import` — Share rules with your team
-
-```bash
-# Export your rules to a file (commit this alongside your code)
-npx @shahmilsaari/memory-core export
-
-# Import from a file or URL
-npx @shahmilsaari/memory-core import
-npx @shahmilsaari/memory-core import --file path/to/rules.json
-npx @shahmilsaari/memory-core import --url https://example.com/team-rules.json
-```
-
-Skips duplicates — safe to run multiple times.
-
----
-
-### `ignore` / `allow` — Handle exceptions
-
-```bash
-# Save a false-positive pattern — never flagged again
-npx @shahmilsaari/memory-core ignore "controllers may import prisma in migration scripts"
-npx @shahmilsaari/memory-core ignore --list
-npx @shahmilsaari/memory-core ignore --remove <id>
-
-# Allow an intentional project pattern
-npx @shahmilsaari/memory-core allow "generated by sqlc"
-npx @shahmilsaari/memory-core allow --list
-```
-
----
-
-### `stats` / `tune` — Manage noisy rules
-
-```bash
-npx @shahmilsaari/memory-core stats           # show violation counts and false-positive rates
-npx @shahmilsaari/memory-core stats --tune    # show only noisy rules with their disable commands
-npx @shahmilsaari/memory-core stats --reset   # clear all counters
-
-npx @shahmilsaari/memory-core tune            # interactively silence noisy rules
-npx @shahmilsaari/memory-core tune --yes      # silence all qualifying rules automatically
-```
-
-A rule with a >40% false-positive rate shows up in `--tune`. The `tune` command lets you silence it interactively.
-
----
-
-### `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 --list
-npx @shahmilsaari/memory-core commit-rules --remove "^WIP"
-```
-
-The `commit-msg` git hook validates every commit message against these rules.
-
----
-
-### `ci-setup` — GitHub Actions integration
-
-```bash
-npx @shahmilsaari/memory-core ci-setup
-```
-
-Generates `.github/workflows/memory-core.yml`. Adds a PR check using `memories.json` — no project database needed in CI.
-
----
-
-### `status` — See your current setup
-
-```bash
-npx @shahmilsaari/memory-core status
-```
-
-Shows project name, provider/model, agents, hook state, generated files, and health checks for PostgreSQL and Ollama.
-
----
-
-### `reset` vs `uninstall` — Cleanup
-
-| Command | What it does | Database |
+| Dependency | Purpose | Install |
 |---|---|---|
-| `reset --soft` | Remove generated agent files only | Kept |
-| `reset` | Remove generated files + config + hook | Kept |
-| `reset --db` | Same as reset + drop memories table | Dropped (with confirmation) |
-| `uninstall` | Remove everything: files, config, hook, gitignore block | Kept |
-| `uninstall --db` | Same as uninstall + drop memories table | Dropped (with confirmation) |
-
-```bash
-npx @shahmilsaari/memory-core reset
-npx @shahmilsaari/memory-core reset --soft
-npx @shahmilsaari/memory-core uninstall
-```
+| 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` |
 
----
+Cloud providers (OpenAI, Anthropic, DeepSeek, any OpenAI-compatible endpoint) can be used for code analysis — embeddings always stay local.
 
 ## Supported AI agents
 
-memory-core generates instruction files for:
-
-| Agent | File |
-|---|---|
-| 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`
-
----
+Claude Code · GitHub Copilot · Cursor · Windsurf · Cline · Roo Code · Aider · Continue.dev · Devin · Amazon Q · Gemini Code Assist · Zed AI · JetBrains AI · OpenHands
 
-## Architecture profiles
+## Key commands
 
-Pick the one that matches your project structure:
-
-**Backend**
-| Profile | Use when… |
-|---|---|
-| Clean Architecture | Strict separation between domain, application, and infrastructure |
-| Modular Monolith | Feature modules that might become microservices later |
-| MVC | Standard controllers + services |
-| Hexagonal | Ports and adapters for maximum testability |
-| Go REST API | Go backend with idiomatic error handling |
-| Laravel | Laravel with service-repository pattern |
-| NestJS | Modules, guards, pipes, DTOs, repository pattern |
-
-**Frontend**
-| Profile | Use when… |
+| Command | Description |
 |---|---|
-| 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 |
-| Nuxt 3 | Fullstack Vue with SSR |
-| React Native | Mobile apps |
+| `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 |
 
----
-
-## AI providers
+See [COMMANDS.md](COMMANDS.md) for the full reference.
 
-| Provider | Setup | Use when |
-|---|---|---|
-| Ollama (default) | Local, no API key | You want free, private, offline AI |
-| OpenAI | `CHAT_API_KEY=sk-...` | You want GPT-4o / GPT-4o-mini quality |
-| Anthropic | `CHAT_API_KEY=sk-ant-...` | You want Claude quality |
-| MiniMax | `CHAT_API_KEY=...` | Cost-effective cloud option |
+## Dashboard
 
-Switch without rerunning init:
 ```bash
-npx @shahmilsaari/memory-core provider set openai --model gpt-4o --api-key sk-...
-npx @shahmilsaari/memory-core model set qwen2.5-coder --provider ollama
+memory-core dashboard
 ```
 
-Or switch from the dashboard UI — takes effect immediately, no restart needed.
-
----
-
-## Environment variables
-
-memory-core creates `.memory-core.env` automatically during `init`.
-
-| Variable | Default | What it does |
-|---|---|---|
-| `DATABASE_URL` | — | PostgreSQL connection string (required) |
-| `OLLAMA_URL` | `http://localhost:11434` | Ollama server URL (used for embeddings) |
-| `OLLAMA_MODEL` | `nomic-embed-text` | Embedding model (always Ollama) |
-| `CHAT_PROVIDER` | `ollama` | Code-checking provider: `ollama`, `openai`, `anthropic`, `minimax` |
-| `CHAT_MODEL` | `llama3.2` | Code-checking model |
-| `CHAT_API_KEY` | — | API key for cloud providers |
-
----
-
-## Troubleshooting
+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
 
-**`extension "vector" is not available`**
-pgvector isn't installed for your PostgreSQL version. Follow the [pgvector steps](#pgvector) above.
+## Environment
 
-**`Ollama not running — skipping rule check`**
-Start Ollama: `brew services start ollama` (macOS) or `ollama serve` (Linux).
+```env
+# PostgreSQL
+DATABASE_URL=postgres://localhost:5432/memory_core
 
-**`Chat model "llama3.2" not found`**
-Run `ollama pull llama3.2`, or switch provider: `npx @shahmilsaari/memory-core provider set openai --model gpt-4o-mini --api-key sk-...`
+# Ollama (local, for embeddings)
+OLLAMA_URL=http://localhost:11434
+OLLAMA_MODEL=nomic-embed-text
 
-**`DATABASE_URL is not set`**
-Run `npx @shahmilsaari/memory-core init` — it creates `.memory-core.env` for you.
+# AI provider for code analysis (choose one)
+CHAT_PROVIDER=ollama
+CHAT_MODEL=qwen2.5-coder:7b
 
-**Not sure what memory-core is using**
-Run `npx @shahmilsaari/memory-core status` or `npx @shahmilsaari/memory-core model doctor`.
-
-**`createdb: role does not exist`**
-```bash
-createuser -s $(whoami)
+# 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-...
 ```
 
-**Hook is flagging something intentional**
-Save an ignore pattern: `npx @shahmilsaari/memory-core ignore "your exception here"`
-
-**I bypassed the hook by accident and now it keeps asking**
-That's bypass tracking. Run `MEMORY_CORE_SKIP_HOOK=1 git commit` with a reason the next time, or run `npx @shahmilsaari/memory-core stats` to see your bypass history.
-
----
-
-## 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 |
-
----
-
-## Roadmap
+## Docs
 
-| | Feature |
-|---|---|
-| ✓ | Watch mode — real-time violation alerts on save |
-| ✓ | AI auto-fix — violations detected → AI rewrites the file |
-| ✓ | Dry-run mode — full check pipeline, exits 0 |
-| ✓ | Schema alignment rules — TypeScript↔Go struct field drift detection |
-| ✓ | Bypass tracking — every hook bypass is counted and visible |
-| ✓ | Token usage tracking — AI call counts across all providers |
-| ✓ | Dashboard model switcher — change provider/model from the UI |
-| ✓ | Dashboard actions panel — Sync, Check All, Tune from UI |
-| ✓ | WebSocket-only stats — live push, no polling |
-| ✓ | Multi-provider code checking — Ollama, OpenAI, Anthropic, MiniMax |
-| ✓ | Pre-commit hook (advisory + strict modes) |
-| ✓ | Commit message linting — `commit-rules` + `commit-msg` hook |
-| ✓ | CI/CD — GitHub Actions workflow generation |
-| ✓ | 14 agent file generators + 3 shared files |
-| ✓ | 281 seeded best-practice rules across 13 architecture profiles |
-| ✓ | AI-powered rule search |
-| ✓ | Export / import — portable `memories.json` |
-| ✓ | Auto-tuning — silence noisy rules interactively |
-| ✓ | False-positive tracking per rule |
-| ✓ | Import graph analysis — structural boundary checking |
-| ✓ | Local Svelte dashboard with WebSocket live feed |
-| | Model guidance during init — recommend model based on machine specs |
-| | Team sync — shared database for the whole team |
-| | Violation → rule pipeline — auto-suggest rules when violations repeat |
-
----
+- [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)*