memorix 1.0.7 → 1.0.8

package/docs/DEVELOPMENT.md

@@ -0,0 +1,317 @@
+# Development Guide
+
+This guide is for contributors working on Memorix itself.
+
+Memorix is a TypeScript project built around:
+
+- MCP server runtime
+- CLI workflows
+- SQLite canonical persistence with compatibility/fallback layers
+- Orama search
+- dashboard and HTTP control plane
+
+## Current Release Baseline
+
+The current published release line is **1.0.8**.
+
+Contributors should assume the following are already part of the supported product surface:
+
+- provenance-aware memory fields and layered retrieval semantics
+- evidence-aware detail and timeline outputs
+- verification-aware and citation-lite compact output
+- task-line scoping, secret-safety, and attribution auditing
+- calibrated retention plus cleanup/remediation loop ergonomics
+- OpenCode `post_compact` support and structured continuation compaction prompt
+
+---
+
+## 1. Prerequisites
+
+- Node.js `>=20`
+- npm
+- Git
+
+Clone and install:
+
+```bash
+git clone https://github.com/AVIDS2/memorix.git
+cd memorix
+npm install
+```
+
+Optional local dependencies:
+
+- `fastembed` for local embedding experiments
+- `@huggingface/transformers` for transformer embedding mode
+
+Memorix still works without them.
+
+---
+
+## 2. Core Commands
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch mode
+
+```bash
+npm run dev
+```
+
+### Typecheck
+
+```bash
+npm run lint
+```
+
+`lint` currently runs `tsc --noEmit`.
+
+### Full test suite
+
+```bash
+npm test
+```
+
+### Vitest watch mode
+
+```bash
+npm run test:watch
+```
+
+### Local runtime checks
+
+```bash
+memorix serve
+memorix background start
+memorix status
+```
+
+---
+
+## 3. Recommended Development Loop
+
+For most feature work:
+
+1. write or update a focused test
+2. implement the change
+3. run the targeted test file
+4. run `npm run lint`
+5. run `npm run build`
+6. run `npm test`
+7. validate the real MCP or CLI path if the feature affects runtime behavior
+
+Examples:
+
+```bash
+npx vitest run tests/git/noise-filter.test.ts
+npm run lint
+npm run build
+npm test
+```
+
+If the feature touches the dashboard, HTTP transport, or MCP wiring, do a live verification after the test suite.
+
+---
+
+## 4. Repository Structure
+
+High-level layout:
+
+```text
+src/
+  cli/                 interactive menu and subcommands
+  compact/             compact formatting and token budgeting
+  config/              YAML, dotenv, and configuration loading
+  dashboard/           dashboard server and static frontend
+  embedding/           embedding providers
+  git/                 Git Memory extractor, hook path, noise filter
+  hooks/               IDE hook normalization and capture
+  llm/                 optional LLM quality helpers
+  memory/              observations, sessions, retention, graph, formation
+  project/             Git-based project detection and aliases
+  rules/               rules sync across agents
+  search/              intent-aware retrieval helpers
+  skills/              memory-driven skills generation
+  store/               Orama index and persistence
+  team/                autonomous Agent Team registry, tasks, locks, messages
+  workspace/           MCP and workflow sync across agents
+
+tests/
+  ...mirrors runtime modules with focused unit and integration tests
+```
+
+Docs layout:
+
+- `README.md`: landing page and quick start
+- `docs/SETUP.md`: client setup and troubleshooting
+- `docs/CONFIGURATION.md`: `memorix.yml + .env`
+- `docs/GIT_MEMORY.md`: Git Memory workflows
+- `docs/ARCHITECTURE.md`: system design
+- `docs/API_REFERENCE.md`: MCP tool surface
+
+---
+
+## 5. Runtime Modes to Validate
+
+### stdio MCP
+
+```bash
+memorix serve
+```
+
+Use this to validate:
+
+- tool registration
+- stdio MCP behavior
+- IDE integration compatibility
+
+### HTTP MCP + dashboard
+
+```bash
+memorix background start
+```
+
+Use this to validate:
+
+- HTTP MCP endpoint
+- Team tools
+- dashboard API parity
+- dashboard UX
+
+Use `memorix serve-http --port 3211` when you want the same stack in the foreground for debugging, manual supervision, or custom ports.
+
+### Dashboard-only mode
+
+```bash
+memorix dashboard
+```
+
+Useful for local UI checks, but the main product dashboard is the one embedded in the HTTP control plane.
+
+---
+
+## 6. Feature Areas Worth Testing Live
+
+Some features deserve real runtime verification, not just tests:
+
+- project identity detection
+- config provenance
+- Git hook installation and post-commit ingest
+- cross-project search and detail refs
+- HTTP transport and Team tools
+- dashboard graph stability and page layout
+
+When validating these, prefer:
+
+- real MCP calls
+- real CLI commands
+- real temporary Git repositories
+
+over only unit tests.
+
+---
+
+## 7. Git Memory Development Notes
+
+Git Memory is one of Memorix's most important product differentiators.
+
+When working in this area, validate:
+
+- `memorix git-hook --force`
+- `memorix git-hook-uninstall`
+- `memorix ingest commit`
+- `memorix ingest commit --force`
+- `memorix ingest log --count N`
+
+Also validate behavior in:
+
+- normal repositories
+- worktrees
+- noisy commit streams
+
+See [GIT_MEMORY.md](GIT_MEMORY.md) for user-facing behavior.
+
+---
+
+## 8. Configuration Development Notes
+
+Memorix is converging on:
+
+- `memorix.yml` for behavior
+- `.env` for secrets
+
+When touching config code, always validate:
+
+- project `memorix.yml`
+- user `~/.memorix/memorix.yml`
+- project `.env`
+- user `~/.memorix/.env`
+- legacy `~/.memorix/config.json`
+- env var overrides
+
+And always check:
+
+```bash
+memorix status
+```
+
+to make sure provenance diagnostics match runtime behavior.
+
+---
+
+## 9. Release Workflow
+
+Recommended release flow:
+
+1. update docs and version metadata
+2. run:
+
+```bash
+npm run lint
+npm run build
+npm test
+```
+
+3. validate key live flows:
+
+- MCP store/search/detail
+- dashboard
+- Git Memory
+- config diagnostics
+
+4. commit and push
+5. publish manually when ready
+
+Notes:
+
+- `prepublishOnly` already runs build + test
+- npm publish is usually manual, especially when 2FA is enabled
+- GitHub release automation should not be treated as a substitute for manual runtime validation
+
+---
+
+## 10. Contribution Standards
+
+When contributing to Memorix:
+
+- keep public docs aligned with runtime behavior
+- prefer explicit, project-safe behavior over clever fallback
+- avoid adding features without a clear product story
+- validate MCP behavior with real calls when changing server logic
+- keep Git Memory, reasoning memory, and retrieval semantics coherent
+
+Memorix is strongest when its engineering truth layer, reasoning layer, and local control plane all stay in sync.
+
+---
+
+## 11. Related Docs
+
+- [Setup Guide](SETUP.md)
+- [Configuration Guide](CONFIGURATION.md)
+- [Git Memory Guide](GIT_MEMORY.md)
+- [Architecture](ARCHITECTURE.md)
+- [API Reference](API_REFERENCE.md)

package/docs/DOCKER.md

@@ -0,0 +1,138 @@
+# Docker Deployment
+
+Memorix supports Docker as an **HTTP control-plane deployment path**.
+
+This Docker flow is for:
+
+- a long-lived `serve-http` control plane
+- the dashboard on port `3211`
+- IDEs and agents that connect over `http://host:3211/mcp`
+
+It is **not** a containerized form of `memorix serve` (stdio MCP).
+
+---
+
+## Quick Start
+
+From the repository root:
+
+```bash
+docker compose up --build -d
+```
+
+Then open:
+
+- dashboard: `http://localhost:3211`
+- MCP endpoint: `http://localhost:3211/mcp`
+- health: `http://localhost:3211/health`
+
+Stop it with:
+
+```bash
+docker compose down
+```
+
+The provided compose file:
+
+- persists Memorix state in a named volume
+- mounts the current repository at `/workspace`
+- sets `MEMORIX_PROJECT_ROOT=/workspace`
+- sets `MEMORIX_SESSION_TIMEOUT_MS=86400000` so long IDE HTTP sessions can remain idle for up to 24 hours
+
+---
+
+## One-Off docker run
+
+If you prefer `docker run`:
+
+```bash
+docker build -t memorix:local .
+docker run --rm -p 3211:3211 -v memorix-data:/data memorix:local
+```
+
+---
+
+## Host Binding
+
+`memorix serve-http` accepts a `--host` flag:
+
+- **Local** (default): binds to `127.0.0.1` — only accessible from the host machine
+- **Docker**: the Dockerfile sets `--host 0.0.0.0` — accessible from outside the container, which is required for port mapping (`-p 3211:3211`) to work
+
+If you run `serve-http` manually inside a container, make sure to pass `--host 0.0.0.0` or the port will not be reachable from the host.
+
+---
+
+## What Docker Support Means
+
+The official Docker artifacts in this repo provide:
+
+- a multi-stage production image
+- an example `compose.yaml`
+- a healthchecked HTTP deployment
+
+Docker support is for the **HTTP control plane**:
+
+- `memorix serve-http`
+- dashboard access
+- HTTP MCP clients pointing at `http://localhost:3211/mcp`
+
+It is not a promise that stdio MCP magically becomes container-friendly.
+
+---
+
+## Important Path Truth
+
+Docker works best when Memorix can **see the repositories it is asked to bind**.
+
+Project-scoped features such as:
+
+- Git-root detection
+- project binding
+- project `memorix.yml`
+- project `.env`
+- Git Memory inspection
+
+depend on the control plane being able to access the repository path.
+
+### Good fit
+
+- Docker Desktop on the same machine as your IDE
+- a compose setup that mounts the repo you are working on into the container
+- `memorix_session_start(projectRoot=...)` using a path visible **inside** the container
+
+### Caveat
+
+If an IDE on machine A sends `projectRoot=/Users/alice/code/app`, but the Docker container running on machine B cannot see that path, Memorix cannot perform project-scoped detection there.
+
+In that case:
+
+- HTTP connectivity still works
+- global/shared memory still works
+- but project-scoped Git/config semantics will not be fully available until the repo is mounted into the container at a visible path
+
+This is a real runtime limitation, not just a documentation preference.
+
+---
+
+## Operations
+
+Useful checks:
+
+```bash
+curl http://localhost:3211/health
+curl http://localhost:3211/api/stats
+docker compose logs -f memorix
+docker compose ps
+```
+
+### HTTP session idle timeout
+
+The HTTP MCP transport defaults to a 30-minute idle timeout. The example `compose.yaml` raises this to 24 hours for IDEs that keep one HTTP MCP session open while the user reads diffs, runs tests, or switches focus.
+
+To change it:
+
+```yaml
+environment:
+  MEMORIX_SESSION_TIMEOUT_MS: 86400000
+```

package/docs/GIT_MEMORY.md

@@ -0,0 +1,221 @@
+# Git Memory Guide
+
+Git Memory is one of Memorix's core differentiators.
+
+Instead of relying only on agent-written notes, Memorix can turn Git history into searchable engineering memory with source provenance.
+
+---
+
+## What Git Memory Stores
+
+Each ingested commit becomes a memory with:
+
+- `source='git'`
+- `commitHash`
+- title and narrative derived from commit metadata
+- changed files
+- inferred observation type
+- extracted concepts and entities
+
+This creates an engineering truth layer that complements reasoning memory and manual observations.
+
+---
+
+## Main Workflows
+
+### Install automatic post-commit capture
+
+```bash
+memorix git-hook --force
+```
+
+This installs a `post-commit` hook that runs:
+
+```bash
+memorix ingest commit --auto
+```
+
+After that, new commits are automatically evaluated and stored as Git memories.
+
+### Remove the hook
+
+```bash
+memorix git-hook-uninstall
+```
+
+### Ingest a single commit manually
+
+```bash
+memorix ingest commit
+```
+
+You can also target a specific ref:
+
+```bash
+memorix ingest commit --ref HEAD~3
+```
+
+### Batch ingest recent history
+
+```bash
+memorix ingest log --count 20
+```
+
+Use this when enabling Git Memory on an existing project and you want recent history backfilled.
+
+---
+
+## Noise Filtering
+
+Not every commit deserves to become long-lived memory.
+
+Memorix applies a Git noise filter before ingesting commits. Depending on commit content and your config, it may skip:
+
+- merge commits
+- trivial typo or formatting commits
+- lockfile-only changes
+- generated-only changes
+- custom excluded patterns
+- commit subjects matching configured noise keywords
+
+If a commit is skipped in interactive mode, Memorix tells you why.
+
+### Override the filter
+
+If you really want to ingest a filtered commit:
+
+```bash
+memorix ingest commit --force
+```
+
+---
+
+## Configuration
+
+Configure Git Memory in `memorix.yml`:
+
+```yml
+git:
+  autoHook: true
+  ingestOnCommit: true
+  maxDiffSize: 500
+  skipMergeCommits: true
+  excludePatterns:
+    - "*.lock"
+    - "dist/**"
+  noiseKeywords:
+    - "^BOT:"
+    - "auto-deploy"
+```
+
+Key settings:
+
+- `autoHook`: install the post-commit hook automatically on startup
+- `ingestOnCommit`: ingest `HEAD` during post-commit execution
+- `maxDiffSize`: cap how much diff content is included
+- `skipMergeCommits`: skip merge commits by default
+- `excludePatterns`: skip commits touching only matching files
+- `noiseKeywords`: skip commits whose subjects match configured patterns
+
+See [CONFIGURATION.md](CONFIGURATION.md) for the full configuration model.
+
+---
+
+## Retrieval Model
+
+Git memories are especially useful for questions like:
+
+- What changed recently?
+- Which commit introduced this behavior?
+- Which files were touched by this feature?
+- When did we ship this fix?
+
+Memorix retrieval is source-aware:
+
+- “what changed” style questions boost Git memories
+- “why did we do this” style questions boost reasoning memories
+- “how did we fix this” style questions can use both
+
+Git memory is not meant to replace reasoning memory. The strongest setup is:
+
+- **Git Memory** for engineering truth
+- **Reasoning Memory** for trade-offs, decisions, and intent
+
+---
+
+## Cross-Linking
+
+Memorix can connect Git memories and reasoning memories through:
+
+- shared entities
+- explicit `relatedCommits`
+- cross-references in detail views
+
+This gives you a layered understanding:
+
+- Git says what changed
+- reasoning says why it changed
+
+---
+
+## Recommended Rollout
+
+For a new project:
+
+1. create `memorix.yml`
+2. enable Git Memory config
+3. install the git hook
+4. optionally ingest recent history
+5. start using reasoning memory alongside Git Memory
+
+Suggested first run:
+
+```bash
+memorix init
+memorix git-hook --force
+memorix ingest log --count 20
+```
+
+---
+
+## Troubleshooting
+
+### The hook installed, but no memories appear
+
+Check:
+
+- you are inside a Git repository
+- the hook file exists
+- the commit was not filtered as noise
+- the project identity is correct
+
+Run:
+
+```bash
+memorix status
+```
+
+### A commit was skipped unexpectedly
+
+Try:
+
+```bash
+memorix ingest commit --force
+```
+
+If that works, your noise filter settings are likely too aggressive.
+
+### Worktree repositories
+
+Memorix resolves the Git hooks directory in a worktree-safe way, so `.git` can be either:
+
+- a directory
+- or a `gitdir:` indirection file
+
+---
+
+## Related Docs
+
+- [Configuration Guide](CONFIGURATION.md)
+- [Setup Guide](SETUP.md)
+- [Architecture](ARCHITECTURE.md)