localmem 0.1.1__tar.gz

localmem-0.1.1/.githooks/audit-triad.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Wide-sweep audit across the entire working tree. Run before publishing
+# and in CI to gate every PR.
+#
+# Exit codes:
+#   0 — clean (no triad/upstream identifiers found)
+#   1 — violations found (CI should fail on this)
+#   2 — script error (git not available, etc.)
+#
+# Skipped: this hooks directory (intentional patterns), .git, .venv,
+# node_modules, dashboard build output.
+
+set -euo pipefail
+
+cd "$(git rev-parse --show-toplevel)" || exit 2
+
+PATTERNS=(
+  'IRIS'
+  'Iris'
+  'iris'
+  'SORIEL'
+  'Soriel'
+  'soriel'
+  'ECHO'
+  'Echo'
+  'MNEMOSYNE'
+  'Mnemosyne'
+  'mnemosyne'
+)
+
+JOINED="$(IFS='|'; echo "${PATTERNS[*]}")"
+
+# Collect candidate matches first, then filter false positives, then decide.
+# `set -e` plus the explicit `|| true` keeps a "no matches" exit (1) from
+# tearing down the script before we can interpret it.
+raw_hits="$(
+  git ls-files \
+    | grep -vE '^(\.githooks/|dashboard/(node_modules|dist)/)' \
+    | xargs grep -nE "\\b(${JOINED})\\b" 2>/dev/null \
+    || true
+)"
+
+# Drop comment lines that just say "echo ..." (shell builtin, not an agent).
+hits="$(
+  echo "${raw_hits}" \
+    | grep -vE '^[^:]*:[0-9]+:[[:space:]]*#.*echo' \
+    || true
+)"
+
+if [[ -z "${hits//[[:space:]]/}" ]]; then
+  echo "no triad identifiers found"
+  exit 0
+fi
+
+echo "audit-triad: violations found"
+echo ""
+echo "${hits}"
+echo ""
+echo "Run with LOCALMEM_BYPASS_TRIAD_SCAN=1 git commit ... to override locally,"
+echo "but CI will still fail on these matches. Rewrite to generic naming first."
+exit 1

localmem-0.1.1/.githooks/pre-commit

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# localmem pre-commit triad scanner.
+#
+# Blocks any staged change that re-introduces private-project identifiers
+# from the upstream MNEMOSYNE codebase. Override only when you know what
+# you are doing:  LOCALMEM_BYPASS_TRIAD_SCAN=1 git commit ...
+#
+# Patterns are intentionally narrow: case-sensitive whole-word matches for
+# the agent names as identifiers. Lowercase "echo" is too noisy (shell
+# builtin) so only the agent-cased forms are blocked. Run
+# `./.githooks/audit-triad.sh` for a wider sweep across the working tree.
+
+set -euo pipefail
+
+if [[ "${LOCALMEM_BYPASS_TRIAD_SCAN:-0}" == "1" ]]; then
+  echo "pre-commit: LOCALMEM_BYPASS_TRIAD_SCAN=1 — skipping triad scanner" >&2
+  exit 0
+fi
+
+PATTERNS=(
+  '\bIRIS\b'
+  '\bIris\b'
+  '\bSORIEL\b'
+  '\bSoriel\b'
+  '\bsoriel\b'
+  '\bECHO\b'
+  '\bMNEMOSYNE\b'
+  '\bMnemosyne\b'
+  '\bmnemosyne\b'
+)
+
+# Combine into one alternation regex for a single grep pass.
+JOINED="$(IFS='|'; echo "${PATTERNS[*]}")"
+
+# Inspect only added lines in staged diff (lines starting with "+" but not
+# "+++"). This way we don't re-flag content that already exists in HEAD.
+STAGED_ADDITIONS="$(git diff --cached --no-color -U0 -- ':(exclude).githooks/*' \
+  | grep -E '^\+' | grep -v '^\+\+\+' || true)"
+
+if [[ -z "${STAGED_ADDITIONS}" ]]; then
+  exit 0
+fi
+
+HITS="$(echo "${STAGED_ADDITIONS}" | grep -nE "${JOINED}" || true)"
+
+if [[ -n "${HITS}" ]]; then
+  echo "" >&2
+  echo "pre-commit: triad scanner blocked the commit." >&2
+  echo "  The following added lines contain private upstream identifiers:" >&2
+  echo "" >&2
+  echo "${HITS}" | sed 's/^/    /' >&2
+  echo "" >&2
+  echo "  Rewrite to use generic naming (wings are user-configurable;" >&2
+  echo "  intelligence detectors are pluggable). To bypass intentionally:" >&2
+  echo "    LOCALMEM_BYPASS_TRIAD_SCAN=1 git commit ..." >&2
+  echo "" >&2
+  exit 1
+fi

localmem-0.1.1/.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels: ["dependencies", "python"]
+    groups:
+      python-minor-and-patch:
+        update-types: ["minor", "patch"]
+
+  - package-ecosystem: npm
+    directory: /dashboard
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels: ["dependencies", "javascript"]
+    groups:
+      dashboard-minor-and-patch:
+        update-types: ["minor", "patch"]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 3
+    labels: ["dependencies", "github-actions"]

localmem-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  audit:
+    name: triad scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Wide-sweep private-identifier audit
+        run: bash .githooks/audit-triad.sh
+
+  tests:
+    name: pytest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install package + dev extras
+        run: pip install -e ".[dev,dashboard,analytics]"
+      - name: Run test suite
+        run: pytest --tb=short -q
+
+  dashboard:
+    name: dashboard build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: dashboard/package-lock.json
+      - name: Install
+        working-directory: dashboard
+        run: npm ci
+      - name: Build
+        working-directory: dashboard
+        run: npm run build

localmem-0.1.1/.gitignore

@@ -0,0 +1,52 @@
+# Archives
+*.tar.gz
+
+# Runtime data
+data/
+*.db
+*.db-wal
+*.db-shm
+graph.json
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual env
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+
+# Frontend
+node_modules/
+dashboard/dist/
+
+# Local env / secrets
+.env
+.env.*
+.env.local
+prune.env
+.secrets
+.mcp.json
+
+# Certificates
+*.pem

localmem-0.1.1/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+All notable changes to localmem.
+
+## [0.1.1] — Security hardening pass
+
+Findings from a multi-model code/security review. Each item below is gated
+by a regression test under `tests/test_security_hardening_v011.py` or
+`tests/integration/test_ws_handshake.py`.
+
+### Security
+
+- **DuckDB SQL allowlist rewritten as AST validation.** The pre-v0.1.1
+  regex blocklist could not stop UNION-SELECT data exfiltration, subquery
+  shapes (`WHERE wing IN (SELECT secret FROM ...)`), DuckDB file readers
+  (`read_csv_auto('/etc/passwd')`, `read_text(...)`, `load_extension(...)`),
+  CHR-encoded keyword reconstruction, recursive-CTE resource exhaustion,
+  or qualified-column probes. `archiver.query_sql(sql_where=...)` now
+  parses the user clause with `sqlglot` (DuckDB dialect) and walks the
+  AST; only the explicit allowlist of node types (boolean ops,
+  comparisons, literals, schema-allowlisted bare columns, `IN`/`BETWEEN`/
+  `LIKE`/`IS`) survives. Any function call, subquery, `UNION`, `WITH`,
+  `CAST`, window, or qualified column rejects the clause. Lexical
+  pre-checks for `;`, `--`, and `/* */` close the parse-truncation hole
+  where `parse_one` silently stopped at the first statement separator.
+  Requires `pip install 'localmem[analytics]'` for `sqlglot>=23`.
+
+- **WebSocket bearer subprotocol no longer echoes the token.** Pre-v0.1.1
+  accepted `Sec-WebSocket-Protocol: bearer.<token>` and echoed the same
+  string back in the 101 Switching Protocols response — exposing the
+  token in proxy logs, browser devtools, and service worker scope. The
+  new handshake takes two subprotocol values
+  (`Sec-WebSocket-Protocol: bearer, <token>`), validates `<token>` with
+  `hmac.compare_digest` against the configured api_key, and accepts the
+  upgrade with `subprotocol="bearer"` only. The token never appears in
+  the response. **Breaking change** for any pre-v0.1.1 dashboard bundle
+  or custom WS client; rebuild the frontend and update clients to send
+  the new two-value subprotocol list.
+
+- **Wing names are charset-constrained.** Wing values flow into archive
+  filesystem paths, JSON payloads, WebSocket frames, and Qdrant payload
+  keys. `LocalmemConfig._validate_wings` now enforces
+  `^[a-z0-9][a-z0-9_-]{0,62}$` (via `re.fullmatch`, so a trailing
+  newline cannot slip past `$`). Rejects `..`, `/`, `\`, whitespace,
+  control characters, non-ASCII payloads (`café`, RTL overrides), and
+  >63-char strings before they can be interpolated into a path.
+
+- **`Entry.importance` is Pydantic-bounded.** Field now declares
+  `Field(default=0.5, ge=0.0, le=1.0)`. The `localmem_update` MCP tool
+  also enforces the bound explicitly (direct attribute assignment
+  bypasses Pydantic). Prevents a hostile client from setting
+  out-of-range importance to dominate retrieval rankings or evade
+  retention thresholds.
+
+### Tests
+
+- 367 unit tests (+62 from v0.1.0). New `tests/test_security_hardening_v011.py`
+  covers AST allowlist accept/reject cases, wing-name charset rules,
+  importance bounds. New `tests/integration/test_ws_handshake.py`
+  proves the WS server never echoes the token in the 101 response and
+  rejects the pre-v0.1.1 `bearer.<token>` form.
+
+## [0.1.0] — Initial public release
+
+First open-source release. Everything below is shipped in v0.1.0.
+
+### Core
+
+- 22 MCP tools (memory CRUD, hybrid search, graph, knowledge triples,
+  wake-up, intelligence, retention, health, metrics) over FastMCP/SSE on
+  port 8781.
+- User-configurable agent wings + reserved `shared` wing for cross-agent
+  context.
+- **Storage**: Qdrant (local or server mode) for hybrid dense + sparse
+  search with RRF fusion; NetworkX directed multigraph with multi-hop
+  traversal and Louvain community detection; SQLite WAL for temporal
+  knowledge triples, agent diaries, taxonomy, and importance scoring with
+  time-decay.
+- **Layered loading** (L0 manifest → L1 critical context → L2 scoped
+  search → L3 verbatim) for token-efficient agent wake-up.
+- **Intelligence engine** with four opt-in pattern detectors (tool
+  sequences, provider preferences, node clusters, cross-wing temporal
+  correlations). Each detector is off by default until you point it at a
+  wing/room or graph selector.
+
+### Lifecycle
+
+- Three-tier graceful forgetting: hot (verbatim) → warm (consolidated
+  summaries grouped by wing/room/week) → cold (`jsonl.zst` archive,
+  hive-partitioned).
+- Pinned entries bypass every retention gate.
+- Per-wing retention policy overrides; `shared` may set `max_age_days:
+  null` to never archive.
+- Background worker with single-flight semantics (Qdrant single-writer).
+- REST trigger endpoints + cron units (launchd, systemd) + CLI
+  (`pin`, `prune`, `archive`).
+- Optional Ollama LLM summarizer (`consolidation.summarizer: "llm"`) with
+  automatic fallback to the deterministic template summarizer.
+
+### Schema & embeddings
+
+- File-based schema migrations under `src/localmem/migrations/v00X_*.py`
+  with `up()`/`down()` callables and hash-edit detection.
+- `localmem migrate-embeddings --to <model>` re-embeds the entire
+  collection offline (snapshot → dump → recreate → re-embed).
+
+### Dashboard
+
+- Read-only browser UI at `dashboard/` (Vite + React + dockview): 10
+  panels for Health, Entries, Metrics, Alerts, Graph, Wings/Rooms,
+  Triples, Diaries, Logs, Admin.
+- FastAPI sidecar on port 8782 with REST + WebSocket.
+
+### Observability
+
+- `localmem_health` and `localmem_metrics` MCP tools with per-tool call
+  counts, p50/p95/p99 latency, per-wing entry counts, retention worker
+  status.
+- `/metrics` Prometheus exposition endpoint (`text/plain;
+  version=0.0.4`) on the dashboard sidecar.
+- Structured logging (text or JSON) with optional
+  `RotatingFileHandler`.
+
+### Security
+
+- Bearer auth on `/api/*` and `/ws` via `dashboard.auth_enabled`.
+- WebSocket auth via `Sec-WebSocket-Protocol: bearer.<key>` subprotocol
+  (no `?token=` in URLs).
+- Constant-time API-key compare (`hmac.compare_digest`).
+- DuckDB SQL allowlist on `archiver.query_sql(sql_where=...)` —
+  rejects statement separators, comments, and mutating keywords.
+- LLM prompt-injection defense — stored content wrapped in delimiters
+  with explicit "data, not commands" instruction; control chars and
+  delimiter mimicry stripped.
+- `${VAR}` / `${VAR:-default}` env-var interpolation across the YAML
+  config so secrets never need to live in the file on disk.
+- CORS `allow_headers` scoped to `["Authorization", "Content-Type"]`.
+
+### Cross-platform deploy
+
+- `deploy/setup-ubuntu.sh`, `deploy/setup-macos.sh`,
+  `deploy/setup-windows.ps1` — each generates a config dir, registers a
+  service (systemd / launchd / Scheduled Tasks), and writes an api_key to
+  a perms-restricted env file.
+- `--auth` and `--qdrant-server <URL>` flags on each installer.
+
+### Tests
+
+- 300 tests across 22 files. Run with `pytest`.

localmem-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jordanaftermidnight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

localmem-0.1.1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: localmem
+Version: 0.1.1
+Summary: Local-first multi-agent memory MCP server with hybrid search, behavioral graphs, knowledge triples, and lifecycle management
+Project-URL: Homepage, https://github.com/jordanaftermidnight/localmem
+Project-URL: Repository, https://github.com/jordanaftermidnight/localmem
+Project-URL: Issues, https://github.com/jordanaftermidnight/localmem/issues
+Author-email: jordanaftermidnight <jordanaftermidnight@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,knowledge-graph,llm,local-first,mcp,memory,qdrant
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: fastembed>=0.4.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: networkx>=3.3
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: qdrant-client>=1.12.0
+Requires-Dist: sentence-transformers>=3.0.0
+Requires-Dist: zstandard>=0.22
+Provides-Extra: analytics
+Requires-Dist: duckdb>=1.0; extra == 'analytics'
+Requires-Dist: sqlglot>=23.0; extra == 'analytics'
+Provides-Extra: dashboard
+Requires-Dist: fastapi>=0.110; extra == 'dashboard'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'dashboard'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# localmem
+
+**Local-first multi-agent memory MCP server.** Persistent storage for LLM
+agents — hybrid (dense + sparse) vector search, behavioral pattern graphs,
+temporal knowledge triples, layered wake-up context, lifecycle management,
+and a read-only browser dashboard. All on-device, no cloud dependencies.
+
+Exposes its functionality over the Model Context Protocol (SSE transport), so
+any MCP-capable client — Claude Code, Cursor, Continue, custom agents — can
+read and write memory through a single shared server.
+
+## Why
+
+Most "memory" for LLM agents is either a flat key-value store or a
+single-agent knowledge graph. Real agent systems need more:
+
+- **Per-agent namespaces.** Each agent's notes, decisions, and observations
+  stay in its own wing. A reserved `shared` wing carries cross-agent context.
+- **Hybrid retrieval.** Dense embeddings catch semantic matches, sparse BM25
+  catches exact terms, RRF fuses both. Either signal alone misses too much.
+- **Behavioral graphs.** Some relationships live in entries; others live in
+  the connections between them — co-occurrence, sequence, community structure.
+- **Temporal knowledge.** Facts change. Knowledge triples track validity
+  windows and surface contradictions automatically.
+- **Graceful forgetting.** Three-tier lifecycle (hot → warm summaries →
+  cold compressed archive) keeps the working set fast without losing history.
+- **Token-aware loading.** Layered wake-up context (L0 manifest → L1 critical
+  → L2 scoped search → L3 verbatim) gives an agent ~170 tokens of high-signal
+  context without pulling the whole store.
+
+## Quick start
+
+```bash
+git clone https://github.com/jordanaftermidnight/localmem.git
+cd localmem
+pip install -e ".[dev]"
+
+# 1. Edit localmem.yaml — at minimum list your agent wings:
+#      wings:
+#        - my_assistant
+#
+# 2. Start the MCP server:
+localmem serve                  # SSE on http://localhost:8781
+
+# 3. (Optional) Start the read-only dashboard:
+pip install -e ".[dashboard]"
+localmem dashboard              # REST + WS on http://localhost:8782
+( cd dashboard && npm install && npm run dev )   # UI on http://localhost:5173
+```
+
+Connect any MCP client to `http://localhost:8781/sse` and the 22 tools below
+become available.
+
+## MCP tools
+
+| Group | Tool | Purpose |
+| --- | --- | --- |
+| Memory (6) | `localmem_store`, `localmem_search`, `localmem_retrieve`, `localmem_update`, `localmem_pin`, `localmem_unpin` | Entry CRUD + hybrid search |
+| Graph (5) | `localmem_graph_add_node`, `localmem_graph_add_edge`, `localmem_graph_query`, `localmem_graph_neighbors`, `localmem_graph_communities` | Behavioral pattern graph |
+| Knowledge (3) | `localmem_triple_assert`, `localmem_triple_query`, `localmem_triple_contradictions` | Temporal triples with contradiction detection |
+| System (3) | `localmem_wake`, `localmem_health`, `localmem_metrics` | Layered wake-up + observability |
+| Intelligence (3) | `localmem_intel_detect`, `localmem_intel_alerts`, `localmem_intel_report` | Pattern detection (opt-in via config) |
+| Operations (2) | `localmem_prune`, `localmem_archive` | Retention triggers |
+
+## Storage stack
+
+- **[Qdrant](https://qdrant.tech/)** — embedded by default (path-backed,
+  single-writer). Switch to a remote Qdrant via `storage.qdrant_mode: server`
+  + `storage.qdrant_url` to unblock live embedding migrations and
+  multi-process writers.
+- **[NetworkX](https://networkx.org/)** — in-process directed multigraph with
+  multi-hop traversal and Louvain community detection.
+- **SQLite** (WAL) — temporal triples, agent diaries, wing/room taxonomy,
+  importance scoring with time-decay.
+
+## Configuration
+
+`localmem.yaml` at the repo root is the single source of truth. The shipped
+defaults run locally with zero edits — set `wings:` to name your agents and
+you're done. See inline comments for every section. Highlights:
+
+- `wings: [list]` — your agent namespaces. `shared` is implicit.
+- `embedding.model` — `all-MiniLM-L6-v2` (384d, fast) or BGE-large (1024d,
+  quality). Switch live with `localmem migrate-embeddings --to <model>`.
+- `retention.enabled: true` — opt in to the three-tier lifecycle.
+- `dashboard.auth_enabled: true` + bearer key for remote dashboard access.
+- `intelligence.detectors.*` — each pattern detector is off until you point
+  it at a specific wing/room (or node selector for the graph cluster
+  detector). Nothing runs you didn't ask for.
+
+Any string value supports `${VAR}` or `${VAR:-default}` env-var
+interpolation, so secrets stay out of YAML on disk.
+
+## Dashboard
+
+A read-only browser UI under `dashboard/` (Vite + React + dockview). 10
+panels: Health, Entries, Metrics, Alerts, Graph, Wings/Rooms, Triples,
+Diaries, Logs, Admin. Pin/unpin and lifecycle triggers live in Admin.
+Localhost-only by default; flip on bearer auth to expose it remotely.
+
+![localmem dashboard](docs/assets/dashboard.png)
+
+## Observability
+
+- `localmem health` and `localmem_health` MCP tool — per-wing entry counts,
+  store connectivity, embedding device, retention worker status.
+- `localmem_metrics` MCP tool — per-tool call counts, p50/p95/p99 latency,
+  error counts (rolling window).
+- `/metrics` Prometheus exposition endpoint on the dashboard sidecar (`text/plain;
+  version=0.0.4`). See [docs/DASHBOARD.md](docs/DASHBOARD.md) for the metric
+  reference and example scrape config.
+- Structured logging (text or JSON) with optional `RotatingFileHandler`. See
+  [docs/LOGGING.md](docs/LOGGING.md) for Loki + Promtail and ELK + Filebeat
+  shipping configs.
+
+## Deployment
+
+`deploy/` contains installer scripts for the three major platforms — each
+generates a config dir, sets up a service (systemd / launchd / Scheduled
+Tasks), and writes an `api_key` to a perms-restricted env file:
+
+```bash
+deploy/setup-ubuntu.sh  --auth --qdrant-server http://qdrant:6333
+deploy/setup-macos.sh   --auth
+deploy/setup-windows.ps1 -Auth
+```
+
+## Documentation
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — full specification
+- [`docs/DASHBOARD.md`](docs/DASHBOARD.md) — dashboard panels, auth, metrics
+- [`docs/LIFECYCLE.md`](docs/LIFECYCLE.md) — retention / consolidation / archive
+- [`docs/MIGRATIONS.md`](docs/MIGRATIONS.md) — schema and embedding migrations
+- [`docs/LOGGING.md`](docs/LOGGING.md) — log shipping recipes
+
+## Project layout
+
+```
+localmem/
+├── src/localmem/         # Package source
+├── dashboard/            # React + dockview frontend
+├── deploy/               # Installers + service units
+├── docs/                 # Architecture, dashboard, lifecycle, migrations, logging
+├── manifests/            # Per-agent wake-up manifests
+├── tests/                # 300+ tests
+├── localmem.yaml         # Default configuration
+└── pyproject.toml
+```
+
+## Known issues
+
+- **Python 3.14 + Apple Silicon + sentence-transformers**: the `loky`
+  process pool used by sentence-transformers can crash silently at shutdown
+  on Python 3.14 / arm64 macOS. Python 3.13 and earlier are unaffected.
+  Either use Python 3.13 (verified end-to-end on this build) or switch to
+  the sparse-only retrieval path via `embedding.model: "Qdrant/bm25"`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).