# NeuralMemory — Version Bump & Feature Reference

> Complete checklist and feature catalog. Update this file when adding new features.

---

## Version Bump Checklist (7 touch points)

| # | File | Line | What | When |
|---|------|------|------|------|
| 1 | `pyproject.toml` | 7 | `version = "0.9.1"` | Every release |
| 2 | `src/neural_memory/__init__.py` | 17 | `__version__ = "0.9.1"` | Every release (must match #1) |
| 3 | `CHANGELOG.md` | 8 | Move `[Unreleased]` to `[X.Y.Z]` | Every release |
| 4 | `vscode-extension/package.json` | 5 | `"version": "0.1.5"` | Every extension release |
| 5 | `vscode-extension/CHANGELOG.md` | 3 | Add `[X.Y.Z] - date` section | Every extension release |
| 6 | `storage/sqlite_schema.py` | 14 | `SCHEMA_VERSION = 4` | Only on DB schema changes |
| 7 | `storage/sqlite_brain_ops.py` + `memory_brain_ops.py` | 108/138 | `version="0.1.0"` | Only on snapshot format changes |

---

## Files That Auto-Read Version (verify after bump)

| File | How |
|------|-----|
| `server/app.py` | `from neural_memory import __version__` — FastAPI metadata + `/health` |
| `mcp/server.py` | `from neural_memory import __version__` — MCP server |
| `cli/commands/info.py` | `version()` command displays `__version__` |
| `cli/update_check.py` | Compares `__version__` vs latest on PyPI |
| `vscode-extension/src/utils/updateChecker.ts` | Reads from `packageJSON.version` |

---

## API Versioning

- `/api/v1/` prefix — only bump on **breaking** API changes
- Legacy unversioned routes kept at `/` for backward compat
- Both defined in `server/app.py`

---

## Release Triggers

| Target | Trigger | Workflow |
|--------|---------|----------|
| Python package (PyPI) | Git tag `v*` | `.github/workflows/release.yml` |
| VS Code extension | Manual `vsce publish` | N/A |
| Docker | Manual build | `Dockerfile` (Python 3.11-slim) |

---

## All CLI Commands

| Command | Description | Key Options |
|---------|-------------|-------------|
| `pug remember` | Store memory | --tag, --type, --priority, --expires, --project, --shared, --force, --redact, --json |
| `pug recall` | Query memories | --depth, --max-tokens, --min-confidence, --show-age, --show-routing, --json |
| `pug context` | Get recent context | --limit, --fresh-only, --json |
| `pug todo` | Quick TODO | --priority, --project, --expires, --tag, --json |
| `pug q` | Quick recall shortcut | -d (depth) |
| `pug a` | Quick add shortcut | -p (priority) |
| `pug last` | Show last N memories | -n (count) |
| `pug today` | Show today's memories | — |
| `pug stats` | Enhanced brain stats | --json |
| `pug status` | Quick status + suggestions | --json |
| `pug check` | Sensitive content detection | --json |
| `pug version` | Show version | — |
| `pug list` | List memories | --type, --min-priority, --project, --expired, --include-expired, --limit, --json |
| `pug cleanup` | Remove expired memories | --expired, --type, --dry-run, --force, --json |
| `pug consolidate` | Prune/merge/summarize | --brain, --strategy, --dry-run, --prune-threshold, --merge-overlap, --min-inactive-days |
| `pug decay` | Run memory decay | --brain |
| `pug init` | Initialize NeuralMemory | — |
| `pug serve` | Run FastAPI server | --host, --port |
| `pug mcp` | Run MCP server | — |
| `pug mcp-config` | Generate MCP config JSON | --with-prompt, --compact |
| `pug prompt` | Show system prompt | --compact, --copy |
| `pug dashboard` | Rich dashboard | — |
| `pug ui` | Interactive browser | — |
| `pug graph` | Graph explorer | — |
| `pug hooks` | Configure hooks | — |
| `pug export` | Export brain to JSON | --brain |
| `pug import` | Import brain from JSON | --brain, --merge, --strategy |
| `pug brain list` | List brains | — |
| `pug brain use` | Switch brain | — |
| `pug brain create` | Create brain | — |
| `pug brain delete` | Delete brain | — |
| `pug brain export` | Export brain | --output, --name, --exclude-sensitive |
| `pug brain import` | Import brain | --name, --use, --scan |
| `pug brain health` | Brain health check | --name, --json |
| `pug project create` | Create project | --description, --duration, --tag, --priority, --json |
| `pug project list` | List projects | --json |
| `pug project show` | Show project details | --json |
| `pug project delete` | Delete project | — |
| `pug project extend` | Extend project duration | — |
| `pug shared enable` | Enable shared mode | --api-key, --timeout |
| `pug shared disable` | Disable shared mode | — |
| `pug shared status` | Show shared mode status | — |
| `pug shared test` | Test shared connection | — |
| `pug shared sync` | Sync local with remote | — |
| `pug index` | Index codebase into neural memory | --ext, --status, --json |
| `pug telegram status` | Show Telegram config status | --json |
| `pug telegram test` | Send test message to configured chats | --json |
| `pug telegram backup` | Send brain .db backup to Telegram | --brain, --json |

---

## All API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Health check + version |
| GET | `/` | API info |
| POST | `/memory/encode` | Encode memory |
| POST | `/memory/query` | Query memories |
| GET | `/memory/fiber/{id}` | Get fiber details |
| GET | `/memory/neurons` | List neurons |
| GET | `/memory/suggest` | Prefix-based neuron suggestions |
| POST | `/memory/index` | Index codebase into neural graph |
| POST | `/brain/create` | Create brain |
| GET | `/brain/{id}` | Get brain details |
| GET | `/brain/{id}/stats` | Enhanced statistics |
| GET | `/brain/{id}/export` | Export brain snapshot |
| POST | `/brain/{id}/import` | Import brain snapshot |
| POST | `/brain/{id}/merge` | Merge brain with conflict resolution |
| POST | `/brain/{id}/consolidate` | Sleep & consolidate |
| DELETE | `/brain/{id}` | Delete brain |
| WS | `/sync/ws` | WebSocket real-time sync |
| GET | `/sync/stats` | Sync statistics |
| GET | `/api/dashboard/stats` | Dashboard overview stats |
| GET | `/api/dashboard/health` | Dashboard health metrics |
| GET | `/api/dashboard/evolution` | Brain evolution data |
| GET | `/api/dashboard/graph` | Graph data for visualization |
| GET | `/api/dashboard/timeline` | Timeline events |
| GET | `/api/dashboard/brain-files` | Brain file paths and sizes |
| GET | `/api/dashboard/telegram/status` | Telegram config status + bot info |
| POST | `/api/dashboard/telegram/test` | Send test message to Telegram |
| POST | `/api/dashboard/telegram/backup` | Send brain backup to Telegram |

> All REST endpoints also available at `/api/v1/` prefix.

---

## All MCP Tools

| Tool | Parameters | Description |
|------|------------|-------------|
| `pugbrain_remember` | content, type?, priority?, tags?, expires_days? | Store a memory |
| `pugbrain_recall` | query, depth?, max_tokens?, min_confidence? | Query memories |
| `pugbrain_context` | limit?, fresh_only? | Get recent context |
| `pugbrain_todo` | task, priority? | Quick TODO (30-day expiry) |
| `pugbrain_stats` | — | Brain statistics |
| `pugbrain_auto` | action (status/enable/disable/analyze/process), text?, save? | Auto-capture from text (with passive recall learning) |
| `pugbrain_suggest` | prefix, limit?, type_filter? | Prefix-based autocomplete suggestions ranked by relevance + frequency |
| `pugbrain_session` | action (get/set/end), feature?, task?, progress?, notes? | Track current working session state for cross-session resume (auto-detects git branch) |
| `pugbrain_index` | action (scan/status), path?, extensions? | Index codebase into neural memory for code-aware recall |
| `pugbrain_telegram_backup` | brain_name? | Send brain .db backup to configured Telegram chats |

**MCP Resources:**
- `neuralmemory://prompt/system` — Full system prompt
- `neuralmemory://prompt/compact` — Compact system prompt

---

## VS Code Extension Features

### Commands (11)

| Command ID | Label | Keybinding |
|------------|-------|------------|
| `neuralmemory.encode` | Encode Selection as Memory | `Ctrl+Shift+M E` |
| `neuralmemory.encodeInput` | Encode Text as Memory | — |
| `neuralmemory.recall` | Recall Memory | `Ctrl+Shift+M R` |
| `neuralmemory.openGraph` | Open Graph Explorer | `Ctrl+Shift+M G` |
| `neuralmemory.switchBrain` | Switch Brain | — |
| `neuralmemory.createBrain` | Create Brain | — |
| `neuralmemory.refreshMemories` | Refresh Memory Tree | — |
| `neuralmemory.startServer` | Start Server | — |
| `neuralmemory.connectServer` | Connect to Server | — |
| `neuralmemory.recallFromTree` | Recall Related Memories | — |
| `neuralmemory.indexCodebase` | Index Codebase | `Ctrl+Shift+M I` |

### Settings (6)

| Setting | Default | Description |
|---------|---------|-------------|
| `neuralmemory.pythonPath` | `"python"` | Python interpreter path |
| `neuralmemory.autoStart` | `false` | Auto-start server on activate |
| `neuralmemory.serverUrl` | `"http://127.0.0.1:8000"` | Server URL |
| `neuralmemory.graphNodeLimit` | `1000` | Max nodes in graph (50-10000) |
| `neuralmemory.codeLensEnabled` | `true` | Show CodeLens hints |
| `neuralmemory.commentTriggers` | `["remember:", "note:", "decision:", "todo:"]` | Comment patterns |

### UI

- **Activity Bar**: Brain icon sidebar
- **Tree View**: "Memories" panel showing neurons and fibers
- **CodeLens**: Inline hints on matching comment patterns
- **Graph Explorer**: Interactive neural graph webview

---

## Auto-Capture System

Brain tự động tích lũy memories qua MCP usage, aligned với "The Key: Associative Reflex" vision.

### How It Works

1. **Passive capture on `pugbrain_recall`**: Queries >=50 chars are analyzed for capturable patterns (fire-and-forget, higher confidence threshold 0.8)
2. **Explicit capture via `pugbrain_auto process`**: Analyze text and save detected memories (respects `enabled` flag)
3. **Pattern analysis via `pugbrain_auto analyze`**: Preview detected patterns without saving

### Detection Patterns (5 categories)

| Category | Confidence | Priority | Example Triggers |
|----------|-----------|----------|-----------------|
| `decision` | 0.8 | 6 | "decided to", "chose X over Y", "quyết định" |
| `error` | 0.85 | 7 | "error:", "bug:", "fixed by", "lỗi do" |
| `todo` | 0.75 | 5 | "TODO:", "need to", "cần phải" |
| `fact` | 0.7 | 5 | "answer is", "works because", "giải pháp là" |
| `insight` | 0.8 | 6 | "turns out", "root cause was", "hóa ra", "TIL" |

### Configuration (`~/.neuralmemory/config.toml`)

```toml
[auto]
enabled = true              # Master switch (default: true)
capture_decisions = true
capture_errors = true
capture_todos = true
capture_facts = true
capture_insights = true     # NEW: "aha moment" detection
min_confidence = 0.7        # Threshold for explicit process
                            # Passive capture uses max(0.8, min_confidence)
```

### Safety Guards

- Minimum text length: 20 chars (avoids false positives on tiny inputs)
- Passive capture: >=50 char queries only, confidence >=0.8
- Fire-and-forget: passive capture errors never break `pugbrain_recall`
- `pugbrain_auto process` enforces `enabled` flag (returns early if disabled)
- Deduplication with type-prefix stripping

### Supported Languages

- English (all 5 categories)
- Vietnamese (decision, error, todo, fact, insight patterns)

---

## Memory Types (11)

| Type | Description |
|------|-------------|
| `fact` | Factual information |
| `decision` | Decisions made |
| `preference` | User preferences |
| `todo` | Tasks to do |
| `insight` | Insights and learnings |
| `context` | Contextual information |
| `instruction` | Instructions and rules |
| `error` | Error patterns |
| `workflow` | Workflow patterns |
| `reference` | Reference material |
| `tool` | Tool usage patterns |

---

## Conflict Strategies (4)

| Strategy | Description |
|----------|-------------|
| `prefer_local` | Keep local version on conflict |
| `prefer_remote` | Keep incoming version on conflict |
| `prefer_recent` | Keep whichever was created/updated more recently |
| `prefer_stronger` | Keep higher weight synapses, higher frequency neurons |

---

## Consolidation Strategies (4)

| Strategy | Description |
|----------|-------------|
| `prune` | Remove weak synapses + orphan neurons |
| `merge` | Combine overlapping fibers (Jaccard similarity) |
| `summarize` | Create concept neurons for tag clusters |
| `all` | Run all strategies in order |

---

## Entry Points (pyproject.toml)

```
neural-memory = neural_memory.cli:main
pug = neural_memory.cli:main
pug-mcp = neural_memory.mcp:main
pug-hook-stop = neural_memory.hooks.stop:main
pug-hook-pre-compact = neural_memory.hooks.pre_compact:main
pug-hook-post-tool-use = neural_memory.hooks.post_tool_use:main
```

---

## Optional Extras

| Extra | Packages |
|-------|----------|
| `server` | fastapi, uvicorn |
| `neo4j` | neo4j driver |
| `nlp-en` | spacy |
| `nlp-vi` | underthesea, pyvi |
| `nlp` | nlp-en + nlp-vi |
| `all` | server + neo4j + nlp |
| `dev` | pytest, pytest-asyncio, pytest-cov, ruff, mypy, pre-commit, httpx |

---

## Test Files (25)

### Unit Tests (17)
- test_neuron, test_synapse, test_fiber, test_brain_mode, test_project
- test_memory_types, test_activation, test_consolidation, test_hebbian
- test_mcp (65 tests: schemas, tool calls, protocol, resources, storage, auto-capture, passive capture, session, index, tokens_used)
- test_codebase (16 tests: git context, AST extraction, codebase encoding)
- test_router, test_safety, test_sqlite_storage
- test_sync, test_temporal, test_typed_memory_storage

### Integration Tests (2)
- test_encoding_flow, test_query_flow

### E2E Tests (1)
- test_api

### Config
- conftest.py (fixtures)

---

## Documentation Files (20)

| File | Topic |
|------|-------|
| `docs/index.md` | Home |
| `docs/installation.md` | Installation guide |
| `docs/quickstart.md` | Quick start |
| `docs/cli.md` | CLI reference |
| `docs/integration.md` | AI assistant integration |
| `docs/mcp-server.md` | MCP server setup |
| `docs/safety.md` | Security best practices |
| `docs/brain-sharing.md` | Brain export/import |
| `docs/memory-types.md` | Memory types |
| `docs/neurons-synapses.md` | Neural architecture |
| `docs/spreading-activation.md` | Retrieval mechanism |
| `docs/how-it-works.md` | System overview |
| `docs/architecture/overview.md` | System design |
| `docs/architecture/scalability.md` | Scalability |
| `docs/api/server.md` | REST API reference |
| `docs/api/python.md` | Python API reference |
| `docs/benchmarks.md` | Performance benchmarks |
| `docs/FAQ.md` | FAQ |
| `docs/changelog.md` | Version history |
| `docs/contributing.md` | Contributing |

---

## Current Versions (as of 2026-03-02)

| Component | Version |
|-----------|---------|
| Python Package | 2.19.0 |
| Database Schema | 20 |
| MCP Tools | 28 |
| Memory Types | 11 |
| Synapse Types | 24 |
| Brain Snapshot Format | 1.0.0 |
| API Prefix | /api/v1 |
| Python Requirement | >=3.11 |
| Docker Base | python:3.11-slim |
