@shahmilsaari/memory-core 0.2.15 → 0.2.17

package/README.md

@@ -4,11 +4,13 @@
 
 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.13**
+Fully local or cloud — your choice. **v0.2.16**
 
 ---
 
@@ -133,6 +135,7 @@ CREATE TABLE IF NOT EXISTS memories (
   title        TEXT,
   content      TEXT NOT NULL,
   reason       TEXT,
+  context      JSONB NOT NULL DEFAULT '{}',
   tags         TEXT[] DEFAULT '{}',
   embedding    vector(768),
   created_at   TIMESTAMP DEFAULT now()
@@ -170,9 +173,33 @@ For the full CLI reference, examples, and command behavior notes, see [COMMANDS.
 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 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`
+
+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
+```
 
 ### `init` — Set up a project
 
@@ -240,6 +267,9 @@ 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"
 ```
 
@@ -248,8 +278,14 @@ npx @shahmilsaari/memory-core remember "Use DTOs for all API responses" \
 | `--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 |
+| `--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
@@ -306,20 +342,46 @@ Options:
 ```bash
 npx @shahmilsaari/memory-core watch --path src/   # watch a specific folder only
 npx @shahmilsaari/memory-core watch --verbose     # show extra details
+npx @shahmilsaari/memory-core watch --debug       # show prompt, diff, and raw model output
 ```
 
 Only checks source files — ignores `node_modules`, `dist`, config files, JSON, etc.
 
 ---
 
+### `dashboard` — Local command center
+
+```bash
+npx @shahmilsaari/memory-core dashboard
+npx @shahmilsaari/memory-core dashboard --port 5178
+npx @shahmilsaari/memory-core dashboard --path src/
+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.
+
+---
+
 ### `check` — Manual check (for CI)
 
 ```bash
 npx @shahmilsaari/memory-core check --staged           # check staged files
 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 --ci               # CI mode using memories.json
 ```
 
-Same as the pre-commit hook. Use this in CI/CD pipelines.
+`--staged` is the same path used by the pre-commit hook. `--ci` reads `memories.json` and uses a deterministic CI-friendly diff check, so pull requests can enforce rules without a local database or Ollama setup.
 
 ---
 
@@ -398,19 +460,41 @@ npx @shahmilsaari/memory-core list --limit 50
 
 ```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, tags, type, or scope.
+Opens the memory interactively so you can update its content, reason, structured context, tags, type, or scope.
 
 ---
 
@@ -431,6 +515,7 @@ Exports all memories from the database to `memories.json` in the project root (o
 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.
@@ -439,6 +524,7 @@ Imports memories into the local database. Skips duplicates by content hash — s
 |---|---|
 | `--file <path>` | Import from a custom local file path |
 | `--url <url>` | Import from a remote URL |
+| `--no-sync` | Skip automatic agent file regeneration |
 
 ---
 
@@ -453,17 +539,30 @@ Saves a pattern so the hook and watcher never flag it again. Useful for intentio
 ```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.
+
+---
+
 ### `ci-setup` — GitHub Actions integration
 
 ```bash
 npx @shahmilsaari/memory-core ci-setup
 ```
 
-Generates `.github/workflows/memory-core.yml`. Adds a PR check that runs your architecture rules on every pull request — same checks as the local hook, enforced in CI.
+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.
 
 ---
 
@@ -477,15 +576,36 @@ Shows which rules fire most often and which files have the most violations. Usef
 
 ---
 
-### `reset` — Remove all generated files
+### `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 all generated files + .memory-core.json
+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
 ```
 
-Cleans up everything memory-core created. Use `--soft` if you want to re-run `init` without losing your saved memories.
+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.
+
+### `uninstall` — Remove memory-core from a project
+
+```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
+```
+
+Use this when you want the project back to a pre-memory-core state. Database deletion is opt-in and only happens with `--db`.
 
 ---
 
@@ -595,6 +715,9 @@ npx @shahmilsaari/memory-core search "caching strategy"
 # Inspect current setup, provider, model, and health checks
 npx @shahmilsaari/memory-core status
 
+# 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
@@ -709,15 +832,16 @@ npm run smoke:npx
 | ✓ | Export / import — portable memories.json for version control and team sharing |
 | ✓ | List / remove / edit — full CRUD for stored memories |
 | ✓ | False positive tagging — `ignore` command saves exceptions for hook and watcher |
-| ✓ | Reset command — clean up generated files and optionally drop the DB table |
+| ✓ | Cleanup commands — `reset` regenerates/reinitializes files; `uninstall` removes memory-core from a project |
 | ✓ | Test suite — smoke tests for all core commands and providers |
 | ✓ | 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 architecture-filtered rules |
+| ✓ | Live config reload — dashboard updates when `.env`, `.memory-core.env`, project config, or stats change |
 | | Model guidance during init — recommend a model based on machine specs |
 | | Violation → rule pipeline — auto-suggest a new rule when the same violation repeats |
-| | Rule analytics dashboard — visual breakdown of rule coverage and violations |
 | | Team sync — shared database so the whole team works from the same rule set |
 
 ---