[IaC] Add CONTRIBUTING.md — assignment-lock protocol and workflow conventions

Closes #1252

- Assignment-as-lock protocol for humans and agents
- Branch naming conventions
- PR requirements (rebase, reference issues, no bytecode)
- Path conventions table
- Feature manifest workflow
- Stale PR policy documentation

.githooks/stale-pr-closer.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════════
+# stale-pr-closer.sh — Auto-close conflicted PRs superseded by
+# already-merged work.
+#
+# Designed for cron on Hermes:
+#   0 */6 * * * /path/to/the-nexus/.githooks/stale-pr-closer.sh
+#
+# Closes #1250 (parent epic #1248)
+# ═══════════════════════════════════════════════════════════════
+set -euo pipefail
+
+# ─── Configuration ──────────────────────────────────────────
+GITEA_URL="${GITEA_URL:-https://forge.alexanderwhitestone.com}"
+GITEA_TOKEN="${GITEA_TOKEN:?Set GITEA_TOKEN env var}"
+REPO="${REPO:-Timmy_Foundation/the-nexus}"
+GRACE_HOURS="${GRACE_HOURS:-24}"
+DRY_RUN="${DRY_RUN:-false}"
+
+API="$GITEA_URL/api/v1"
+AUTH="Authorization: token $GITEA_TOKEN"
+
+log() { echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $*"; }
+
+# ─── Fetch open PRs ────────────────────────────────────────
+log "Checking open PRs for $REPO (grace period: ${GRACE_HOURS}h, dry_run: $DRY_RUN)"
+
+OPEN_PRS=$(curl -s -H "$AUTH" "$API/repos/$REPO/pulls?state=open&limit=50")
+PR_COUNT=$(echo "$OPEN_PRS" | python3 -c "import json,sys; print(len(json.loads(sys.stdin.read())))")
+
+if [ "$PR_COUNT" = "0" ]; then
+    log "No open PRs. Done."
+    exit 0
+fi
+
+log "Found $PR_COUNT open PR(s)"
+
+# ─── Fetch recently merged PRs (for supersession check) ────
+MERGED_PRS=$(curl -s -H "$AUTH" "$API/repos/$REPO/pulls?state=closed&limit=100&sort=updated&direction=desc")
+
+# ─── Process each open PR ──────────────────────────────────
+echo "$OPEN_PRS" | python3 -c "
+import json, sys, re
+from datetime import datetime, timedelta, timezone
+
+grace_hours = int('$GRACE_HOURS')
+dry_run = '$DRY_RUN' == 'true'
+api = '$API'
+repo = '$REPO'
+
+open_prs = json.loads(sys.stdin.read())
+
+# Read merged PRs from file we'll pipe separately
+# (We handle this in the shell wrapper below)
+" 2>/dev/null || true
+
+# Use Python for the complex logic
+python3 << 'PYEOF'
+import json, sys, os, re, subprocess
+from datetime import datetime, timedelta, timezone
+
+GITEA_URL = os.environ.get("GITEA_URL", "https://forge.alexanderwhitestone.com")
+GITEA_TOKEN = os.environ["GITEA_TOKEN"]
+REPO = os.environ.get("REPO", "Timmy_Foundation/the-nexus")
+GRACE_HOURS = int(os.environ.get("GRACE_HOURS", "24"))
+DRY_RUN = os.environ.get("DRY_RUN", "false") == "true"
+
+API = f"{GITEA_URL}/api/v1"
+HEADERS = {"Authorization": f"token {GITEA_TOKEN}", "Content-Type": "application/json"}
+
+import urllib.request, urllib.error
+
+def api_get(path):
+    req = urllib.request.Request(f"{API}{path}", headers=HEADERS)
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())
+
+def api_post(path, data):
+    body = json.dumps(data).encode()
+    req = urllib.request.Request(f"{API}{path}", data=body, headers=HEADERS, method="POST")
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())
+
+def api_patch(path, data):
+    body = json.dumps(data).encode()
+    req = urllib.request.Request(f"{API}{path}", data=body, headers=HEADERS, method="PATCH")
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())
+
+def log(msg):
+    from datetime import datetime, timezone
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    print(f"[{ts}] {msg}")
+
+now = datetime.now(timezone.utc)
+cutoff = now - timedelta(hours=GRACE_HOURS)
+
+# Fetch open PRs
+open_prs = api_get(f"/repos/{REPO}/pulls?state=open&limit=50")
+if not open_prs:
+    log("No open PRs. Done.")
+    sys.exit(0)
+
+log(f"Found {len(open_prs)} open PR(s)")
+
+# Fetch recently merged PRs
+merged_prs = api_get(f"/repos/{REPO}/pulls?state=closed&limit=100&sort=updated&direction=desc")
+merged_prs = [p for p in merged_prs if p.get("merged")]
+
+# Build lookup: issue_number -> merged PR that closes it
+# Parse "Closes #NNN" from merged PR bodies
+def extract_closes(body):
+    if not body:
+        return set()
+    return set(int(m) for m in re.findall(r'(?:closes?|fixes?|resolves?)\s+#(\d+)', body, re.IGNORECASE))
+
+merged_by_issue = {}
+for mp in merged_prs:
+    for issue_num in extract_closes(mp.get("body", "")):
+        merged_by_issue[issue_num] = mp
+
+# Also build a lookup by title similarity (for PRs that implement same feature without referencing same issue)
+merged_by_title_words = {}
+for mp in merged_prs:
+    # Extract meaningful words from title
+    title = re.sub(r'\[claude\]|\[.*?\]|feat\(.*?\):', '', mp.get("title", "")).strip().lower()
+    words = set(w for w in re.findall(r'\w+', title) if len(w) > 3)
+    if words:
+        merged_by_title_words[mp["number"]] = (words, mp)
+
+closed_count = 0
+
+for pr in open_prs:
+    pr_num = pr["number"]
+    pr_title = pr["title"]
+    mergeable = pr.get("mergeable", True)
+    updated_at = datetime.fromisoformat(pr["updated_at"].replace("Z", "+00:00"))
+    
+    # Skip if within grace period
+    if updated_at > cutoff:
+        log(f"  PR #{pr_num}: within grace period, skipping")
+        continue
+    
+    # Check 1: Is it conflicted?
+    if mergeable:
+        log(f"  PR #{pr_num}: mergeable, skipping")
+        continue
+    
+    # Check 2: Does a merged PR close the same issue?
+    pr_closes = extract_closes(pr.get("body", ""))
+    superseded_by = None
+    
+    for issue_num in pr_closes:
+        if issue_num in merged_by_issue:
+            superseded_by = merged_by_issue[issue_num]
+            break
+    
+    # Check 3: Title similarity match (if no issue match)
+    if not superseded_by:
+        pr_title_clean = re.sub(r'\[.*?\]|feat\(.*?\):', '', pr_title).strip().lower()
+        pr_words = set(w for w in re.findall(r'\w+', pr_title_clean) if len(w) > 3)
+        
+        best_overlap = 0
+        for mp_num, (mp_words, mp) in merged_by_title_words.items():
+            if mp_num == pr_num:
+                continue
+            overlap = len(pr_words & mp_words)
+            # Require at least 60% word overlap
+            if pr_words and overlap / len(pr_words) >= 0.6 and overlap > best_overlap:
+                best_overlap = overlap
+                superseded_by = mp
+    
+    if not superseded_by:
+        log(f"  PR #{pr_num}: conflicted but no superseding PR found, skipping")
+        continue
+    
+    sup_num = superseded_by["number"]
+    sup_title = superseded_by["title"]
+    merged_at = superseded_by.get("merged_at", "unknown")[:10]
+    
+    comment = (
+        f"**Auto-closed by stale-pr-closer**\n\n"
+        f"This PR has merge conflicts and has been superseded by #{sup_num} "
+        f"(\"{sup_title}\"), merged {merged_at}.\n\n"
+        f"If this PR contains unique work not covered by #{sup_num}, "
+        f"please reopen and rebase against `main`."
+    )
+    
+    if DRY_RUN:
+        log(f"  [DRY RUN] Would close PR #{pr_num} — superseded by #{sup_num}")
+    else:
+        # Post comment
+        api_post(f"/repos/{REPO}/issues/{pr_num}/comments", {"body": comment})
+        # Close PR
+        api_patch(f"/repos/{REPO}/pulls/{pr_num}", {"state": "closed"})
+        log(f"  Closed PR #{pr_num} — superseded by #{sup_num} ({sup_title})")
+    
+    closed_count += 1
+
+log(f"Done. {'Would close' if DRY_RUN else 'Closed'} {closed_count} stale PR(s).")
+PYEOF

.gitignore

@@ -1,10 +1,18 @@
+# === Python bytecode (recursive — covers all subdirectories) ===
+**/__pycache__/
+*.pyc
+*.pyo
+
+# === Node ===
 node_modules/
+
+# === Test artifacts ===
 test-results/
-nexus/__pycache__/
-tests/__pycache__/
-mempalace/__pycache__/
+test-screenshots/
+
+# === Tool configs ===
 .aider*
 
-# Prevent agents from writing to wrong path (see issue #1145)
+# === Path guardrails (see issue #1145) ===
+# Prevent agents from writing to wrong path
 public/nexus/
-test-screenshots/

CONTRIBUTING.md

@@ -1,206 +1,54 @@
-# Contribution & Code Review Policy
+# Contributing to The Nexus
+
+## Issue Assignment — The Lock Protocol
+
+**Rule: Assign before you code.**
+
+Before starting work on any issue, you **must** assign it to yourself. If an issue is already assigned to someone else, **do not submit a competing PR**.
+
+### For Humans
+
+1. Check the issue is unassigned
+2. Assign yourself via the Gitea UI (right sidebar → Assignees)
+3. Start coding
+
+### For Agents (Claude, Perplexity, Mimo, etc.)
+
+1. Before generating code, call the Gitea API to check assignment:
+   ```
+   GET /api/v1/repos/{owner}/{repo}/issues/{number}
+   → Check assignees array
+   ```
+2. If unassigned, self-assign:
+   ```
+   POST /api/v1/repos/{owner}/{repo}/issues/{number}/assignees
+   {"assignees": ["your-username"]}
+   ```
+3. If already assigned, **stop**. Post a comment offering to help instead.
+
+### Why This Matters
+
+On April 11, 2026, we found 12 stale PRs caused by Rockachopa and the `[claude]` auto-bot racing on the same issues. The auto-bot merged first, orphaning the manual PRs. Assignment-as-lock prevents this race condition.
+
+---
 
 ## Branch Protection & Review Policy
 
-All repositories enforce these rules on the `main` branch:
-- ✅ Require Pull Request for merge
-- ✅ Require 1 approval before merge
-- ✅ Dismiss stale approvals on new commits
-- <20>️ Require CI to pass (where CI exists)
-- ✅ Block force pushes to `main`
-- ✅ Block deletion of `main` branch
+All repositories enforce these rules on `main`:
 
-### Default Reviewer Assignments
-
-| Repository       | Required Reviewers              |
-|------------------|---------------------------------|
-| `hermes-agent`   | `@perplexity`, `@Timmy`         |
-| `the-nexus`      | `@perplexity`                   |
-| `timmy-home`     | `@perplexity`                   |
-| `timmy-config`   | `@perplexity`                   |
-
-### CI Enforcement Status
-
-| Repository       | CI Status                       |
-|------------------|---------------------------------|
-| `hermes-agent`   | ✅ Active                       |
-| `the-nexus`      | <20>️ CI runner pending (#915)    |
-| `timmy-home`     | ❌ No CI                        |
-| `timmy-config`   | ❌ Limited CI                   |
-
-### Workflow Requirements
-
-1. Create feature branch from `main`
-2. Submit PR with clear description
-3. Wait for @perplexity review
-4. Address feedback if any
-5. Merge after approval and passing CI
-
-### Emergency Exceptions
-Hotfixes require:
-- ✅ @Timmy approval
-- ✅ Post-merge documentation
-- ✅ Follow-up PR for full review
-
-### Abandoned PR Policy
-- PRs inactive >7 day: 🧹 archived
-- Unreviewed PRs >14 days: ❌ closed
-
-### Policy Enforcement
-These rules are enforced by Gitea branch protection settings. Direct pushes to main will be blocked.
-- Require rebase to re-enable
-
-## Enforcement
-
-These rules are enforced by Gitea's branch protection settings. Violations will be blocked at the platform level.
-# Contribution and Code Review Policy
-
-## Branch Protection Rules
-
-All repositories must enforce the following rules on the `main` branch:
-- ✅ Require Pull Request for merge
-- ✅ Require 1 approval before merge
-- ✅ Dismiss stale approvals when new commits are pushed
-- ✅ Require status checks to pass (where CI is configured)
-- ✅ Block force-pushing to `main`
-- ✅ Block deleting the `main` branch
-
-## Default Reviewer Assignment
-
-All repositories must configure the following default reviewers:
-- `@perplexity` as default reviewer for all repositories
-- `@Timmy` as required reviewer for `hermes-agent`
-- Repo-specific owners for specialized areas
-
-## Implementation Status
-
-| Repository       | Branch Protection | CI Enforcement | Default Reviewers |
-|------------------|------------------|----------------|-------------------|
-| hermes-agent     | ✅ Enabled        | ✅ Active        | @perplexity, @Timmy |
-| the-nexus        | ✅ Enabled        | ⚠️ CI pending    | @perplexity       |
-| timmy-home       | ✅ Enabled        | ❌ No CI         | @perplexity       |
-| timmy-config     | ✅ Enabled        | ❌ No CI         | @perplexity       |
-
-## Compliance Requirements
-
-All contributors must:
-1. Never push directly to `main`
-2. Create a pull request for all changes
-3. Get at least one approval before merging
-4. Ensure CI passes before merging (where applicable)
-
-## Policy Enforcement
-
-This policy is enforced via Gitea branch protection rules. Violations will be blocked at the platform level.
-
-For questions about this policy, contact @perplexity or @Timmy.
-
-### Required for All Merges
-- [x] Pull Request must exist for all changes
-- [x] At least 1 approval from reviewer
-- [x] CI checks must pass (where applicable)
-- [x] No force pushes allowed
-- [x] No direct pushes to main
-- [x] No branch deletion
-
-### Review Requirements
-- [x] @perplexity must be assigned as reviewer
-- [x] @Timmy must review all changes to `hermes-agent/`
-- [x] No self-approvals allowed
-
-### CI/CD Enforcement
-- [x] CI must be configured for all new features
-- [x] Failing CI blocks merge
-- [x] CI status displayed in PR header
-
-### Abandoned PR Policy
-- PRs inactive >7 days get "needs attention" label
-- PRs inactive >21 days are archived
-- PRs inactive >90 days are closed
-- [ ] At least 1 approval from reviewer
-- [ ] CI checks must pass (where available)
-- [ ] No force pushes allowed
-- [ ] No direct pushes to main
-- [ ] No branch deletion
-
-### Review Requirements by Repository
-```yaml
-hermes-agent:
-  required_owners:
-    - perplexity
-    - Timmy
-
-the-nexus:
-  required_owners:
-    - perplexity
-
-timmy-home:
-  required_owners:
-    - perplexity
-
-timmy-config:
-  required_owners:
-    - perplexity
-```
-
-### CI Status
-
-```text
-- hermes-agent: ✅ Active
-- the-nexus: ⚠️ CI runner disabled (see #915)
-- timmy-home: - (No CI)
-- timmy-config: - (Limited CI)
-```
-
-### Branch Protection Status
-
-All repositories now enforce:
-- Require PR for merge
-- 1+ approvals required
-- CI/CD must pass (where applicable)
-- Force push and branch deletion blocked
-- hermes-agent: ✅ Active
-- the-nexus: ⚠️ CI runner disabled (see #915)
-- timmy-home: - (No CI)
-- timmy-config: - (Limited CI)
-```
-
-## Workflow
-1. Create feature branch
-2. Open PR against main
-3. Get 1+ approvals
-4. Ensure CI passes
-5. Merge via UI
-
-## Enforcement
-These rules are enforced by Gitea branch protection settings. Direct pushes to main will be blocked.
-
-## Abandoned PRs
-PRs not updated in >7 days will be labeled "stale" and may be closed after 30 days of inactivity.
-# Contributing to the Nexus
-
-**Every PR: net ≤ 10 added lines.** Not a guideline — a hard limit.
-Add 40, remove 30. Can't remove? You're homebrewing. Import instead.
-
-## Branch Protection & Review Policy
-
-### Branch Protection Rules
-
-All repositories enforce the following rules on the `main` branch:
-
-| Rule | Status | Applies To |
-|------|--------|------------|
-| Require Pull Request for merge | ✅ Enabled | All |
-| Require 1 approval before merge | ✅ Enabled | All |
-| Dismiss stale approvals on new commits | ✅ Enabled | All |
-| Require CI to pass (where CI exists) | ⚠️ Conditional | All |
-| Block force pushes to `main` | ✅ Enabled | All |
-| Block deletion of `main` branch | ✅ Enabled | All |
+| Rule | Status |
+|------|--------|
+| Require Pull Request for merge | ✅ Enabled |
+| Require 1 approval before merge | ✅ Enabled |
+| Dismiss stale approvals on new commits | ✅ Enabled |
+| Require CI to pass (where CI exists) | ⚠️ Conditional |
+| Block force pushes to `main` | ✅ Enabled |
+| Block deletion of `main` branch | ✅ Enabled |
 
 ### Default Reviewer Assignments
 
 | Repository | Required Reviewers |
-|------------|------------------|
+|------------|-------------------|
 | `hermes-agent` | `@perplexity`, `@Timmy` |
 | `the-nexus` | `@perplexity` |
 | `timmy-home` | `@perplexity` |
@@ -215,199 +63,93 @@ All repositories enforce the following rules on the `main` branch:
 | `timmy-home` | ❌ No CI |
 | `timmy-config` | ❌ Limited CI |
 
-### Review Requirements
+---
 
-- All PRs must be reviewed by at least one reviewer
-- `@perplexity` is the default reviewer for all repositories
-- `@Timmy` is a required reviewer for `hermes-agent`
+## Branch Naming
 
-All repositories enforce:
-- ✅ Require Pull Request for merge
-- ✅ Require 1 approval
-- ⚠<> Require CI to pass (CI runner pending)
-- ✅ Dismiss stale approvals on new commits
-- ✅ Block force pushes
-- ✅ Block branch deletion
+Use descriptive prefixes:
 
-## Review Requirements
+| Prefix | Use |
+|--------|-----|
+| `feat/` | New features |
+| `fix/` | Bug fixes |
+| `epic/` | Multi-issue epic branches |
+| `docs/` | Documentation only |
 
-- Mandatory reviewer: `@perplexity` for all repos
-- Mandatory reviewer: `@Timmy` for `hermes-agent/`
-- Optional: Add repo-specific owners for specialized areas
+Example: `feat/mnemosyne-memory-decay`
 
-## Implementation Status
+---
 
-- ✅ hermes-agent: All protections enabled
-- ✅ the-nexus: PR + 1 approval enforced
-- ✅ timmy-home: PR + 1 approval enforced
-- ✅ timmy-config: PR + 1 approval enforced
+## PR Requirements
 
-> CI enforcement pending runner restoration (#915)
+1. **Rebase before merge** — PRs must be up-to-date with `main`. If you have merge conflicts, rebase locally and force-push.
+2. **Reference the issue** — Use `Closes #NNN` in the PR body so Gitea auto-closes the issue on merge.
+3. **No bytecode** — Never commit `__pycache__/` or `.pyc` files. The `.gitignore` handles this, but double-check.
+4. **One feature per PR** — Avoid omnibus PRs that bundle multiple unrelated features. They're harder to review and more likely to conflict.
 
-## What gets preserved from legacy Matrix
+---
 
-High-value candidates include:
-- visitor movement / embodiment
-- chat, bark, and presence systems
-- transcript logging
-- ambient / visual atmosphere systems
-- economy / satflow visualizations
-- smoke and browser validation discipline
+## Path Conventions
 
-Those
-```
+| Module | Canon Path |
+|--------|-----------|
+| Mnemosyne (backend) | `nexus/mnemosyne/` |
+| Mnemosyne (frontend) | `nexus/components/` |
+| MemPalace | `nexus/mempalace/` |
+| Scripts/tools | `bin/` |
+| Git hooks/automation | `.githooks/` |
+| Tests | `nexus/mnemosyne/tests/` |
 
-README.md
-````
-<<<<<<< SEARCH
-# Contribution & Code Review Policy
+**Never** create a duplicate module at the repo root (e.g., `mnemosyne/` when `nexus/mnemosyne/` already exists). Check `FEATURES.yaml` manifests for the canonical path.
 
-## Branch Protection Rules (Enforced via Gitea)
-All repositories must have the following branch protection rules enabled on the `main` branch:
+---
 
-1. **Require Pull Request for Merge**  
-   - Prevent direct commits to `main`
-   - All changes must go through PR process
+## Feature Manifests
 
-# Contribution & Code Review Policy
+Each major module maintains a `FEATURES.yaml` manifest that declares:
+- What exists (status: `shipped`)
+- What's in progress (status: `in-progress`, with assignee)
+- What's planned (status: `planned`)
 
-## Branch Protection & Review Policy
+**Check the manifest before creating new PRs.** If your feature is already shipped, you're duplicating work. If it's in-progress by someone else, coordinate.
 
-See [POLICY.md](POLICY.md) for full branch protection rules and review requirements. All repositories must enforce:
+Current manifests:
+- [`nexus/mnemosyne/FEATURES.yaml`](nexus/mnemosyne/FEATURES.yaml)
 
-- Require Pull Request for merge
-- 1+ required approvals
-- Dismiss stale approvals
-- Require CI to pass (where CI exists)
-- Block force push
-- Block branch deletion
-
-Default reviewers:
-- @perplexity (all repositories)
-- @Timmy (hermes-agent only)
-
-### Repository-Specific Configuration
-
-**1. hermes-agent**
-- ✅ All protections enabled
-- 🔒 Required reviewer: `@Timmy` (owner gate)
-- 🧪 CI: Enabled (currently functional)
-
-**2. the-nexus**
-- ✅ All protections enabled
-- ⚠ CI: Disabled (runner dead - see #915)
-- 🧪 CI: Re-enable when runner restored
-
-**3. timmy-home**
-- ✅ PR + 1 approval required
-- 🧪 CI: No CI configured
-
-**4. timmy-config**
-- ✅ PR + 1 approval required
-- 🧪 CI: Limited CI
-
-### Default Reviewer Assignment
-
-All repositories must:
-- 🧑‍ Default reviewer: `@perplexity` (QA gate)
-- 🧑 Required reviewer: `@Timmy` for `hermes-agent/` only
-
-### Acceptance Criteria
-
-- [x] All four repositories have protection rules applied
-- [x] Default reviewers configured per matrix above
-- [x] This policy documented in all repositories
-- [x] Policy enforced for 72 hours with no unreviewed merges
-
-> This policy replaces all previous ad-hoc workflows. Any exceptions require written approval from @Timmy and @perplexity.
-All repositories enforce:
-- ✅ Require Pull Request for merge
-- ✅ Minimum 1 approval required
-- ✅ Dismiss stale approvals on new commits
-- ⚠️ Require CI to pass (CI runner pending for the-nexus)
-- ✅ Block force push to `main`
-- ✅ Block deletion of `main` branch
-
-## Review Requirement
-- 🧑‍ Default reviewer: `@perplexity` (QA gate)
-- 🧑 Required reviewer: `@Timmy` for `hermes-agent/` only
+---
 
 ## Workflow
-1. Create feature branch from `main`
-2. Submit PR with clear description
-3. Wait for @perplexity review
-4. Address feedback if any
-5. Merge after approval and passing CI
+
+1. Check the issue is unassigned → self-assign
+2. Check `FEATURES.yaml` for the relevant module
+3. Create feature branch from `main`
+4. Submit PR with clear description and `Closes #NNN`
+5. Wait for reviewer approval
+6. Rebase if needed, then merge
+
+### Emergency Exceptions
+
+Hotfixes require:
+- ✅ @Timmy approval
+- ✅ Post-merge documentation
+- ✅ Follow-up PR for full review
+
+---
+
+## Stale PR Policy
+
+A cron job runs every 6 hours and auto-closes PRs that are:
+1. **Conflicted** (not mergeable)
+2. **Superseded** by a merged PR that closes the same issue or implements the same feature
+
+Closed PRs receive a comment explaining which PR superseded them. If your PR was auto-closed but contains unique work, reopen it, rebase against `main`, and update the feature manifest.
+
+---
 
 ## CI/CD Requirements
-- All main branch merge require:
-  - ✅ Linting
-  - ✅ Unit tests
-  - ⚠️ Integration tests (pending for the-nexus)
-  - ✅ Security scans
 
-## Exceptions
-- Emergency hotfixes require:
-  - ✅ @Timmy approval
-  - ✅ Post-merge documentation
-  - ✅ Follow-up PR for full review
-
-## Abandoned PRs
-- PRs inactive >7 days: 🧹 archived
-- Unreviewed PRs >14 days: ❌ closed
-
-## CI Status
-- ✅ hermes-agent: CI active
-- <20>️ the-nexus: CI runner dead (see #915)
-- ✅ timmy-home: No CI
-- <20>️ timmy-config: Limited CI
->>>>>>> replace
-```
-
-CODEOWNERS
-```text
-<<<<<<< search
-# Contribution & Code Review Policy
-
-## Branch Protection Rules
-All repositories must:
-- ✅ Require PR for merge
-- ✅ Require 1 approval
-- ✅ Dismiss stale approvals
-- ⚠️ Require CI to pass (where exists)
-- ✅ Block force push
-- ✅ block branch deletion
-
-## Review Requirements
-- 🧑 Default reviewer: `@perplexity` for all repos
-- 🧑 Required reviewer: `@Timmy` for `hermes-agent/`
-
-## Workflow
-1. Create feature branch from `main`
-2. Submit PR with clear description
-3. Wait for @perplexity review
-4. Address feedback if any
-5. Merge after approval and passing CI
-
-## CI/CD Requirements
-- All main branch merges require:
-  - ✅ Linting
-  - ✅ Unit tests
-  - ⚠️ Integration tests (pending for the-nexus)
-  - ✅ Security scans
-
-## Exceptions
-- Emergency hotfixes require:
-  - ✅ @Timmy approval
-  - ✅ Post-merge documentation
-  - ✅ Follow-up PR for full review
-
-## Abandoned PRs
-- PRs inactive >7 days: 🧹 archived
-- Unreviewed PRs >14 days: ❌ closed
-
-## CI Status
-- ✅ hermes-agent: ci active
-- ⚠️ the-nexus: ci runner dead (see #915)
-- ✅ timmy-home: No ci
-- ⚠️ timmy-config: Limited ci
+All main branch merges require (where applicable):
+- ✅ Linting
+- ✅ Unit tests
+- ⚠️ Integration tests (pending for the-nexus, see #915)
+- ✅ Security scans

index.html

@@ -477,6 +477,10 @@ index.html
   <div id="memory-inspect-panel" class="memory-inspect-panel" style="display:none;" aria-label="Memory Inspect Panel">
   </div>
 
+  <!-- Memory Connections Panel (Mnemosyne) -->
+  <div id="memory-connections-panel" class="memory-connections-panel" style="display:none;" aria-label="Memory Connections Panel">
+  </div>
+
 <script>
 // ─── MNEMOSYNE: Memory Filter Panel ───────────────────
 function openMemoryFilter() {

nexus/components/memory-connections.js

@@ -0,0 +1,291 @@
+// ═══════════════════════════════════════════════════════════
+// MNEMOSYNE — Memory Connection Panel
+// ═══════════════════════════════════════════════════════════
+//
+// Interactive panel for browsing, adding, and removing memory
+// connections. Opens as a sub-panel from MemoryInspect when
+// a memory crystal is selected.
+//
+// Usage from app.js:
+//   MemoryConnections.init({
+//     onNavigate: fn(memId),        // fly to another memory
+//     onConnectionChange: fn(memId, newConnections) // update hooks
+//   });
+//   MemoryConnections.show(memData, allMemories);
+//   MemoryConnections.hide();
+//
+// Depends on: SpatialMemory (for updateMemory + highlightMemory)
+// ═══════════════════════════════════════════════════════════
+
+const MemoryConnections = (() => {
+  let _panel = null;
+  let _onNavigate = null;
+  let _onConnectionChange = null;
+  let _currentMemId = null;
+  let _hoveredConnId = null;
+
+  // ─── INIT ────────────────────────────────────────────────
+  function init(opts = {}) {
+    _onNavigate = opts.onNavigate || null;
+    _onConnectionChange = opts.onConnectionChange || null;
+    _panel = document.getElementById('memory-connections-panel');
+    if (!_panel) {
+      console.warn('[MemoryConnections] Panel element #memory-connections-panel not found in DOM');
+    }
+  }
+
+  // ─── SHOW ────────────────────────────────────────────────
+  function show(memData, allMemories) {
+    if (!_panel || !memData) return;
+
+    _currentMemId = memData.id;
+    const connections = memData.connections || [];
+    const connectedSet = new Set(connections);
+
+    // Build lookup for connected memories
+    const memLookup = {};
+    (allMemories || []).forEach(m => { memLookup[m.id] = m; });
+
+    // Connected memories list
+    let connectedHtml = '';
+    if (connections.length > 0) {
+      connectedHtml = connections.map(cid => {
+        const cm = memLookup[cid];
+        const label = cm ? _truncate(cm.content || cid, 40) : cid;
+        const cat = cm ? cm.category : '';
+        const strength = cm ? Math.round((cm.strength || 0.7) * 100) : 70;
+        return `
+          <div class="mc-conn-item" data-memid="${_esc(cid)}">
+            <div class="mc-conn-info">
+              <span class="mc-conn-label" title="${_esc(cid)}">${_esc(label)}</span>
+              <span class="mc-conn-meta">${_esc(cat)} · ${strength}%</span>
+            </div>
+            <div class="mc-conn-actions">
+              <button class="mc-btn mc-btn-nav" data-nav="${_esc(cid)}" title="Navigate to memory">⮞</button>
+              <button class="mc-btn mc-btn-remove" data-remove="${_esc(cid)}" title="Remove connection">✕</button>
+            </div>
+          </div>`;
+      }).join('');
+    } else {
+      connectedHtml = '<div class="mc-empty">No connections yet</div>';
+    }
+
+    // Find nearby unconnected memories (same region, then other regions)
+    const suggestions = _findSuggestions(memData, allMemories, connectedSet);
+    let suggestHtml = '';
+    if (suggestions.length > 0) {
+      suggestHtml = suggestions.map(s => {
+        const label = _truncate(s.content || s.id, 36);
+        const cat = s.category || '';
+        const proximity = s._proximity || '';
+        return `
+          <div class="mc-suggest-item" data-memid="${_esc(s.id)}">
+            <div class="mc-suggest-info">
+              <span class="mc-suggest-label" title="${_esc(s.id)}">${_esc(label)}</span>
+              <span class="mc-suggest-meta">${_esc(cat)} · ${_esc(proximity)}</span>
+            </div>
+            <button class="mc-btn mc-btn-add" data-add="${_esc(s.id)}" title="Add connection">+</button>
+          </div>`;
+      }).join('');
+    } else {
+      suggestHtml = '<div class="mc-empty">No nearby memories to connect</div>';
+    }
+
+    _panel.innerHTML = `
+      <div class="mc-header">
+        <span class="mc-title">⬡ Connections</span>
+        <button class="mc-close" id="mc-close-btn" aria-label="Close connections panel">✕</button>
+      </div>
+      <div class="mc-section">
+        <div class="mc-section-label">LINKED (${connections.length})</div>
+        <div class="mc-conn-list" id="mc-conn-list">${connectedHtml}</div>
+      </div>
+      <div class="mc-section">
+        <div class="mc-section-label">SUGGESTED</div>
+        <div class="mc-suggest-list" id="mc-suggest-list">${suggestHtml}</div>
+      </div>
+    `;
+
+    // Wire close button
+    _panel.querySelector('#mc-close-btn')?.addEventListener('click', hide);
+
+    // Wire navigation buttons
+    _panel.querySelectorAll('[data-nav]').forEach(btn => {
+      btn.addEventListener('click', () => {
+        if (_onNavigate) _onNavigate(btn.dataset.nav);
+      });
+    });
+
+    // Wire remove buttons
+    _panel.querySelectorAll('[data-remove]').forEach(btn => {
+      btn.addEventListener('click', () => _removeConnection(btn.dataset.remove));
+    });
+
+    // Wire add buttons
+    _panel.querySelectorAll('[data-add]').forEach(btn => {
+      btn.addEventListener('click', () => _addConnection(btn.dataset.add));
+    });
+
+    // Wire hover highlight for connection items
+    _panel.querySelectorAll('.mc-conn-item').forEach(item => {
+      item.addEventListener('mouseenter', () => _highlightConnection(item.dataset.memid));
+      item.addEventListener('mouseleave', _clearConnectionHighlight);
+    });
+
+    _panel.style.display = 'flex';
+    requestAnimationFrame(() => _panel.classList.add('mc-visible'));
+  }
+
+  // ─── HIDE ────────────────────────────────────────────────
+  function hide() {
+    if (!_panel) return;
+    _clearConnectionHighlight();
+    _panel.classList.remove('mc-visible');
+    const onEnd = () => {
+      _panel.style.display = 'none';
+      _panel.removeEventListener('transitionend', onEnd);
+    };
+    _panel.addEventListener('transitionend', onEnd);
+    setTimeout(() => { if (_panel) _panel.style.display = 'none'; }, 350);
+    _currentMemId = null;
+  }
+
+  // ─── SUGGESTION ENGINE ──────────────────────────────────
+  function _findSuggestions(memData, allMemories, connectedSet) {
+    if (!allMemories) return [];
+
+    const suggestions = [];
+    const pos = memData.position || [0, 0, 0];
+    const sameRegion = memData.category || 'working';
+
+    for (const m of allMemories) {
+      if (m.id === memData.id) continue;
+      if (connectedSet.has(m.id)) continue;
+
+      const mpos = m.position || [0, 0, 0];
+      const dist = Math.sqrt(
+        (pos[0] - mpos[0]) ** 2 +
+        (pos[1] - mpos[1]) ** 2 +
+        (pos[2] - mpos[2]) ** 2
+      );
+
+      // Categorize proximity
+      let proximity = 'nearby';
+      if (m.category === sameRegion) {
+        proximity = dist < 5 ? 'same region · close' : 'same region';
+      } else {
+        proximity = dist < 10 ? 'adjacent' : 'distant';
+      }
+
+      suggestions.push({ ...m, _dist: dist, _proximity: proximity });
+    }
+
+    // Sort: same region first, then by distance
+    suggestions.sort((a, b) => {
+      const aSame = a.category === sameRegion ? 0 : 1;
+      const bSame = b.category === sameRegion ? 0 : 1;
+      if (aSame !== bSame) return aSame - bSame;
+      return a._dist - b._dist;
+    });
+
+    return suggestions.slice(0, 8); // Cap at 8 suggestions
+  }
+
+  // ─── CONNECTION ACTIONS ─────────────────────────────────
+  function _addConnection(targetId) {
+    if (!_currentMemId) return;
+
+    // Get current memory data via SpatialMemory
+    const allMems = typeof SpatialMemory !== 'undefined' ? SpatialMemory.getAllMemories() : [];
+    const current = allMems.find(m => m.id === _currentMemId);
+    if (!current) return;
+
+    const conns = [...(current.connections || [])];
+    if (conns.includes(targetId)) return;
+
+    conns.push(targetId);
+
+    // Update SpatialMemory
+    if (typeof SpatialMemory !== 'undefined') {
+      SpatialMemory.updateMemory(_currentMemId, { connections: conns });
+    }
+
+    // Also create reverse connection on target
+    const target = allMems.find(m => m.id === targetId);
+    if (target) {
+      const targetConns = [...(target.connections || [])];
+      if (!targetConns.includes(_currentMemId)) {
+        targetConns.push(_currentMemId);
+        SpatialMemory.updateMemory(targetId, { connections: targetConns });
+      }
+    }
+
+    if (_onConnectionChange) _onConnectionChange(_currentMemId, conns);
+
+    // Re-render panel
+    const updatedMem = { ...current, connections: conns };
+    show(updatedMem, allMems);
+  }
+
+  function _removeConnection(targetId) {
+    if (!_currentMemId) return;
+
+    const allMems = typeof SpatialMemory !== 'undefined' ? SpatialMemory.getAllMemories() : [];
+    const current = allMems.find(m => m.id === _currentMemId);
+    if (!current) return;
+
+    const conns = (current.connections || []).filter(c => c !== targetId);
+
+    if (typeof SpatialMemory !== 'undefined') {
+      SpatialMemory.updateMemory(_currentMemId, { connections: conns });
+    }
+
+    // Also remove reverse connection
+    const target = allMems.find(m => m.id === targetId);
+    if (target) {
+      const targetConns = (target.connections || []).filter(c => c !== _currentMemId);
+      SpatialMemory.updateMemory(targetId, { connections: targetConns });
+    }
+
+    if (_onConnectionChange) _onConnectionChange(_currentMemId, conns);
+
+    const updatedMem = { ...current, connections: conns };
+    show(updatedMem, allMems);
+  }
+
+  // ─── 3D HIGHLIGHT ───────────────────────────────────────
+  function _highlightConnection(memId) {
+    _hoveredConnId = memId;
+    if (typeof SpatialMemory !== 'undefined') {
+      SpatialMemory.highlightMemory(memId);
+    }
+  }
+
+  function _clearConnectionHighlight() {
+    if (_hoveredConnId && typeof SpatialMemory !== 'undefined') {
+      SpatialMemory.clearHighlight();
+    }
+    _hoveredConnId = null;
+  }
+
+  // ─── HELPERS ────────────────────────────────────────────
+  function _esc(str) {
+    return String(str)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+
+  function _truncate(str, n) {
+    return str.length > n ? str.slice(0, n - 1) + '\u2026' : str;
+  }
+
+  function isOpen() {
+    return _panel != null && _panel.style.display !== 'none';
+  }
+
+  return { init, show, hide, isOpen };
+})();
+
+export { MemoryConnections };

nexus/mnemosyne/FEATURES.yaml

@@ -0,0 +1,184 @@
+# ═══════════════════════════════════════════════════════════════
+# FEATURES.yaml — Mnemosyne Module Manifest
+# ═══════════════════════════════════════════════════════════════
+#
+# Single source of truth for what exists, what's planned, and
+# who owns what. Agents and humans MUST check this before
+# creating new PRs for Mnemosyne features.
+#
+# Statuses: shipped | in-progress | planned | deprecated
+# Canon path: nexus/mnemosyne/
+#
+# Parent epic: #1248 (IaC Workflow)
+# Created: 2026-04-12
+# ═══════════════════════════════════════════════════════════════
+
+project: mnemosyne
+canon_path: nexus/mnemosyne/
+description: The Living Holographic Archive — memory persistence, search, and graph analysis
+
+# ─── Backend Modules ───────────────────────────────────────
+modules:
+
+  archive:
+    status: shipped
+    files: [archive.py]
+    description: Core MnemosyneArchive class — CRUD, search, graph analysis
+    features:
+      - add / get / remove entries
+      - keyword search (substring match)
+      - semantic search (Jaccard + link-boost via HolographicLinker)
+      - linked entry traversal (BFS by depth)
+      - topic filtering and counts
+      - export (JSON/Markdown)
+      - graph data export (nodes + edges for 3D viz)
+      - graph clusters (connected components)
+      - hub entries (highest degree centrality)
+      - bridge entries (articulation points via DFS)
+      - tag management (add_tags, remove_tags, retag)
+      - entry update with content dedup (content_hash)
+      - find_duplicate (content hash matching)
+      - temporal queries (by_date_range, temporal_neighbors)
+      - rebuild_links (re-run linker across all entries)
+    merged_prs:
+      - "#1217"   # Phase 1 foundation
+      - "#1225"   # Semantic search
+      - "#1220"   # Export, deletion, richer stats
+      - "#1234"   # Graph clusters, hubs, bridges
+      - "#1238"   # Tag management
+      - "#1241"   # Entry update + content dedup
+      - "#1246"   # Temporal queries
+
+  entry:
+    status: shipped
+    files: [entry.py]
+    description: ArchiveEntry dataclass — id, title, content, topics, links, timestamps, content_hash
+
+  ingest:
+    status: shipped
+    files: [ingest.py]
+    description: Document ingestion pipeline — chunking, dedup, auto-linking
+
+  linker:
+    status: shipped
+    files: [linker.py]
+    description: HolographicLinker — Jaccard token similarity, auto-link discovery
+
+  cli:
+    status: shipped
+    files: [cli.py]
+    description: CLI interface — stats, search, ingest, link, topics, remove, export, clusters, hubs, bridges, rebuild, tag/untag/retag, timeline, neighbors
+
+  tests:
+    status: shipped
+    files:
+      - tests/__init__.py
+      - tests/test_archive.py
+      - tests/test_graph_clusters.py
+    description: Test suite covering archive CRUD, search, graph analysis, clusters
+
+# ─── Frontend Components ───────────────────────────────────
+# Located in nexus/components/ (shared with other Nexus features)
+
+frontend:
+
+  spatial_memory:
+    status: shipped
+    files: [nexus/components/spatial-memory.js]
+    description: 3D memory crystal rendering and spatial layout
+
+  memory_search:
+    status: shipped
+    files: [nexus/components/spatial-memory.js]
+    description: searchByContent() — text search through holographic archive
+    merged_prs:
+      - "#1201"  # Spatial search
+
+  memory_filter:
+    status: shipped
+    files: [] # inline in index.html
+    description: Toggle memory categories by region
+    merged_prs:
+      - "#1213"
+
+  memory_inspector:
+    status: shipped
+    files: [nexus/components/memory-inspect.js]
+    description: Click-to-inspect detail panel for memory crystals
+    merged_prs:
+      - "#1229"
+
+  memory_connections:
+    status: shipped
+    files: [nexus/components/memory-connections.js]
+    description: Browse, add, remove memory relationships panel
+    merged_prs:
+      - "#1247"
+
+  memory_birth:
+    status: shipped
+    files: [nexus/components/memory-birth.js]
+    description: Birth animation when new memories are created
+    merged_prs:
+      - "#1222"
+
+  memory_particles:
+    status: shipped
+    files: [nexus/components/memory-particles.js]
+    description: Ambient particle system — memory activity visualization
+    merged_prs:
+      - "#1205"
+
+  memory_optimizer:
+    status: shipped
+    files: [nexus/components/memory-optimizer.js]
+    description: Performance optimization for large memory sets
+
+  timeline_scrubber:
+    status: shipped
+    files: [nexus/components/timeline-scrubber.js]
+    description: Temporal navigation scrubber for memory timeline
+
+  health_dashboard:
+    status: shipped
+    files: [] # overlay in index.html
+    description: Archive statistics overlay panel
+    merged_prs:
+      - "#1211"
+
+# ─── Planned / Unshipped ──────────────────────────────────
+
+planned:
+
+  memory_decay:
+    status: planned
+    description: >
+      Memories have living energy that fades with neglect and
+      brightens with access. Vitality score based on access
+      frequency and recency. Was attempted in PR #1221 but
+      went stale — needs fresh implementation against current main.
+    priority: medium
+
+  memory_pulse:
+    status: planned
+    description: >
+      Visual pulse wave radiates through connection graph when
+      a crystal is clicked, illuminating linked memories by BFS
+      hop distance. Was attempted in PR #1226 — needs rebasing.
+    priority: medium
+
+  embedding_backend:
+    status: planned
+    description: >
+      Pluggable embedding backend for true semantic search
+      (replacing Jaccard token similarity). Support local models
+      via Ollama for sovereignty.
+    priority: high
+
+  memory_consolidation:
+    status: planned
+    description: >
+      Automatic merging of duplicate/near-duplicate memories
+      using content_hash and semantic similarity. Periodic
+      consolidation pass.
+    priority: low

nexus/mnemosyne/archive.py

@@ -7,7 +7,7 @@ and provides query interfaces for retrieving connected knowledge.
 from __future__ import annotations
 
 import json
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Optional
 
@@ -651,6 +651,68 @@ class MnemosyneArchive:
         self._save()
         return entry
 
+    @staticmethod
+    def _parse_dt(dt_str: str) -> datetime:
+        """Parse an ISO datetime string. Assumes UTC if no timezone is specified."""
+        dt = datetime.fromisoformat(dt_str)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt
+
+    def by_date_range(self, start: str, end: str) -> list[ArchiveEntry]:
+        """Return entries whose ``created_at`` falls within [start, end] (inclusive).
+
+        Args:
+            start: ISO datetime string for the range start (e.g. "2024-01-01" or
+                   "2024-01-01T00:00:00Z"). Timezone-naive strings are treated as UTC.
+            end: ISO datetime string for the range end. Timezone-naive strings are
+                 treated as UTC.
+
+        Returns:
+            List of ArchiveEntry sorted by ``created_at`` ascending.
+        """
+        start_dt = self._parse_dt(start)
+        end_dt = self._parse_dt(end)
+        results = []
+        for entry in self._entries.values():
+            entry_dt = self._parse_dt(entry.created_at)
+            if start_dt <= entry_dt <= end_dt:
+                results.append(entry)
+        results.sort(key=lambda e: e.created_at)
+        return results
+
+    def temporal_neighbors(self, entry_id: str, window_days: int = 7) -> list[ArchiveEntry]:
+        """Return entries created within ``window_days`` of a given entry.
+
+        The reference entry itself is excluded from results.
+
+        Args:
+            entry_id: ID of the anchor entry.
+            window_days: Number of days around the anchor's ``created_at`` to search.
+
+        Returns:
+            List of ArchiveEntry sorted by ``created_at`` ascending.
+
+        Raises:
+            KeyError: If ``entry_id`` does not exist in the archive.
+        """
+        anchor = self._entries.get(entry_id)
+        if anchor is None:
+            raise KeyError(entry_id)
+        anchor_dt = self._parse_dt(anchor.created_at)
+        delta = timedelta(days=window_days)
+        window_start = anchor_dt - delta
+        window_end = anchor_dt + delta
+        results = []
+        for entry in self._entries.values():
+            if entry.id == entry_id:
+                continue
+            entry_dt = self._parse_dt(entry.created_at)
+            if window_start <= entry_dt <= window_end:
+                results.append(entry)
+        results.sort(key=lambda e: e.created_at)
+        return results
+
     def rebuild_links(self, threshold: Optional[float] = None) -> int:
         """Recompute all links from scratch.
 

nexus/mnemosyne/cli.py

@@ -3,7 +3,8 @@
 Provides: mnemosyne ingest, mnemosyne search, mnemosyne link, mnemosyne stats,
           mnemosyne topics, mnemosyne remove, mnemosyne export,
           mnemosyne clusters, mnemosyne hubs, mnemosyne bridges, mnemosyne rebuild,
-          mnemosyne tag, mnemosyne untag, mnemosyne retag
+          mnemosyne tag, mnemosyne untag, mnemosyne retag,
+          mnemosyne timeline, mnemosyne neighbors
 """
 
 from __future__ import annotations
@@ -180,6 +181,38 @@ def cmd_retag(args):
     print(f"  Topics: {', '.join(entry.topics) if entry.topics else '(none)'}")
 
 
+def cmd_timeline(args):
+    archive = MnemosyneArchive()
+    try:
+        results = archive.by_date_range(args.start, args.end)
+    except ValueError as e:
+        print(f"Invalid date format: {e}")
+        sys.exit(1)
+    if not results:
+        print("No entries found in that date range.")
+        return
+    for entry in results:
+        print(f"[{entry.id[:8]}] {entry.created_at[:10]}  {entry.title}")
+        print(f"  Topics: {', '.join(entry.topics) if entry.topics else '(none)'}")
+        print()
+
+
+def cmd_neighbors(args):
+    archive = MnemosyneArchive()
+    try:
+        results = archive.temporal_neighbors(args.entry_id, window_days=args.days)
+    except KeyError:
+        print(f"Entry not found: {args.entry_id}")
+        sys.exit(1)
+    if not results:
+        print("No temporal neighbors found.")
+        return
+    for entry in results:
+        print(f"[{entry.id[:8]}] {entry.created_at[:10]}  {entry.title}")
+        print(f"  Topics: {', '.join(entry.topics) if entry.topics else '(none)'}")
+        print()
+
+
 def main():
     parser = argparse.ArgumentParser(prog="mnemosyne", description="The Living Holographic Archive")
     sub = parser.add_subparsers(dest="command")
@@ -233,6 +266,14 @@ def main():
     rt.add_argument("entry_id", help="Entry ID")
     rt.add_argument("tags", help="Comma-separated new tag list")
 
+    tl = sub.add_parser("timeline", help="Show entries within an ISO date range")
+    tl.add_argument("start", help="Start datetime (ISO format, e.g. 2024-01-01 or 2024-01-01T00:00:00Z)")
+    tl.add_argument("end", help="End datetime (ISO format)")
+
+    nb = sub.add_parser("neighbors", help="Show entries temporally near a given entry")
+    nb.add_argument("entry_id", help="Anchor entry ID")
+    nb.add_argument("--days", type=int, default=7, help="Window in days (default: 7)")
+
     args = parser.parse_args()
     if not args.command:
         parser.print_help()
@@ -253,6 +294,8 @@ def main():
         "tag": cmd_tag,
         "untag": cmd_untag,
         "retag": cmd_retag,
+        "timeline": cmd_timeline,
+        "neighbors": cmd_neighbors,
     }
     dispatch[args.command](args)
 

nexus/mnemosyne/tests/test_archive.py

@@ -2,6 +2,7 @@
 
 import json
 import tempfile
+from datetime import datetime, timezone, timedelta
 from pathlib import Path
 
 from nexus.mnemosyne.entry import ArchiveEntry
@@ -666,3 +667,189 @@ def test_update_entry_no_change_no_crash():
         e = ingest_event(archive, title="T", content="c")
         result = archive.update_entry(e.id)
         assert result.title == "T"
+
+
+# --- by_date_range tests ---
+
+def _make_entry_at(archive: MnemosyneArchive, title: str, dt: datetime) -> ArchiveEntry:
+    """Helper: ingest an entry and backdate its created_at."""
+    e = ingest_event(archive, title=title, content=title)
+    e.created_at = dt.isoformat()
+    archive._save()
+    return e
+
+
+def test_by_date_range_empty_archive():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        results = archive.by_date_range("2024-01-01", "2024-12-31")
+        assert results == []
+
+
+def test_by_date_range_returns_matching_entries():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        jan = datetime(2024, 1, 15, tzinfo=timezone.utc)
+        mar = datetime(2024, 3, 10, tzinfo=timezone.utc)
+        jun = datetime(2024, 6, 1, tzinfo=timezone.utc)
+        e1 = _make_entry_at(archive, "Jan entry", jan)
+        e2 = _make_entry_at(archive, "Mar entry", mar)
+        e3 = _make_entry_at(archive, "Jun entry", jun)
+
+        results = archive.by_date_range("2024-01-01", "2024-04-01")
+        ids = {e.id for e in results}
+        assert e1.id in ids
+        assert e2.id in ids
+        assert e3.id not in ids
+
+
+def test_by_date_range_boundary_inclusive():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        exact = datetime(2024, 3, 1, tzinfo=timezone.utc)
+        e = _make_entry_at(archive, "Exact boundary", exact)
+
+        results = archive.by_date_range("2024-03-01T00:00:00+00:00", "2024-03-01T00:00:00+00:00")
+        assert len(results) == 1
+        assert results[0].id == e.id
+
+
+def test_by_date_range_no_results():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        jan = datetime(2024, 1, 15, tzinfo=timezone.utc)
+        _make_entry_at(archive, "Jan entry", jan)
+
+        results = archive.by_date_range("2023-01-01", "2023-12-31")
+        assert results == []
+
+
+def test_by_date_range_timezone_naive_treated_as_utc():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        dt = datetime(2024, 6, 15, tzinfo=timezone.utc)
+        e = _make_entry_at(archive, "Summer", dt)
+
+        # Timezone-naive start/end should still match
+        results = archive.by_date_range("2024-06-01", "2024-07-01")
+        assert any(r.id == e.id for r in results)
+
+
+def test_by_date_range_sorted_ascending():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        dates = [
+            datetime(2024, 3, 5, tzinfo=timezone.utc),
+            datetime(2024, 1, 10, tzinfo=timezone.utc),
+            datetime(2024, 2, 20, tzinfo=timezone.utc),
+        ]
+        for i, dt in enumerate(dates):
+            _make_entry_at(archive, f"Entry {i}", dt)
+
+        results = archive.by_date_range("2024-01-01", "2024-12-31")
+        assert len(results) == 3
+        assert results[0].created_at < results[1].created_at < results[2].created_at
+
+
+def test_by_date_range_single_entry_archive():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        dt = datetime(2024, 5, 1, tzinfo=timezone.utc)
+        e = _make_entry_at(archive, "Only", dt)
+
+        assert archive.by_date_range("2024-01-01", "2024-12-31") == [e]
+        assert archive.by_date_range("2025-01-01", "2025-12-31") == []
+
+
+# --- temporal_neighbors tests ---
+
+def test_temporal_neighbors_empty_archive():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        e = ingest_event(archive, title="Lone", content="c")
+        results = archive.temporal_neighbors(e.id, window_days=7)
+        assert results == []
+
+
+def test_temporal_neighbors_missing_entry_raises():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        try:
+            archive.temporal_neighbors("nonexistent-id")
+            assert False, "Expected KeyError"
+        except KeyError:
+            pass
+
+
+def test_temporal_neighbors_returns_within_window():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        anchor_dt = datetime(2024, 4, 10, tzinfo=timezone.utc)
+        near_dt = datetime(2024, 4, 14, tzinfo=timezone.utc)   # +4 days — within 7
+        far_dt = datetime(2024, 4, 20, tzinfo=timezone.utc)    # +10 days — outside 7
+
+        anchor = _make_entry_at(archive, "Anchor", anchor_dt)
+        near = _make_entry_at(archive, "Near", near_dt)
+        far = _make_entry_at(archive, "Far", far_dt)
+
+        results = archive.temporal_neighbors(anchor.id, window_days=7)
+        ids = {e.id for e in results}
+        assert near.id in ids
+        assert far.id not in ids
+        assert anchor.id not in ids
+
+
+def test_temporal_neighbors_excludes_anchor():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        dt = datetime(2024, 4, 10, tzinfo=timezone.utc)
+        anchor = _make_entry_at(archive, "Anchor", dt)
+        same = _make_entry_at(archive, "Same day", dt)
+
+        results = archive.temporal_neighbors(anchor.id, window_days=0)
+        ids = {e.id for e in results}
+        assert anchor.id not in ids
+        assert same.id in ids
+
+
+def test_temporal_neighbors_custom_window():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        anchor_dt = datetime(2024, 4, 10, tzinfo=timezone.utc)
+        within_3 = datetime(2024, 4, 12, tzinfo=timezone.utc)   # +2 days
+        outside_3 = datetime(2024, 4, 15, tzinfo=timezone.utc)  # +5 days
+
+        anchor = _make_entry_at(archive, "Anchor", anchor_dt)
+        e_near = _make_entry_at(archive, "Near", within_3)
+        e_far = _make_entry_at(archive, "Far", outside_3)
+
+        results = archive.temporal_neighbors(anchor.id, window_days=3)
+        ids = {e.id for e in results}
+        assert e_near.id in ids
+        assert e_far.id not in ids
+
+
+def test_temporal_neighbors_sorted_ascending():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        anchor_dt = datetime(2024, 6, 15, tzinfo=timezone.utc)
+        anchor = _make_entry_at(archive, "Anchor", anchor_dt)
+        for offset in [5, 1, 3]:
+            _make_entry_at(archive, f"Offset {offset}", anchor_dt + timedelta(days=offset))
+
+        results = archive.temporal_neighbors(anchor.id, window_days=7)
+        assert len(results) == 3
+        assert results[0].created_at < results[1].created_at < results[2].created_at
+
+
+def test_temporal_neighbors_boundary_inclusive():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = MnemosyneArchive(archive_path=Path(tmp) / "a.json")
+        anchor_dt = datetime(2024, 6, 15, tzinfo=timezone.utc)
+        boundary_dt = anchor_dt + timedelta(days=7)  # exactly at window edge
+
+        anchor = _make_entry_at(archive, "Anchor", anchor_dt)
+        boundary = _make_entry_at(archive, "Boundary", boundary_dt)
+
+        results = archive.temporal_neighbors(anchor.id, window_days=7)
+        assert any(r.id == boundary.id for r in results)

style.css

@@ -1917,3 +1917,163 @@ canvas#nexus-canvas {
   background: rgba(74, 240, 192, 0.18);
   border-color: #4af0c0;
 }
+
+/* ═══ MNEMOSYNE: Memory Connections Panel ═══ */
+.memory-connections-panel {
+  position: fixed;
+  top: 50%;
+  right: 280px;
+  transform: translateY(-50%) translateX(12px);
+  width: 260px;
+  max-height: 70vh;
+  background: rgba(10, 12, 18, 0.92);
+  border: 1px solid rgba(74, 240, 192, 0.15);
+  border-radius: 8px;
+  box-shadow: 0 8px 32px rgba(0,0,0,0.5);
+  z-index: 310;
+  display: flex;
+  flex-direction: column;
+  opacity: 0;
+  transition: opacity 0.2s ease, transform 0.2s ease;
+  backdrop-filter: blur(8px);
+  -webkit-backdrop-filter: blur(8px);
+  font-family: var(--font-mono, monospace);
+}
+.memory-connections-panel.mc-visible {
+  opacity: 1;
+  transform: translateY(-50%) translateX(0);
+}
+
+.mc-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 14px;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+}
+.mc-title {
+  color: rgba(74, 240, 192, 0.8);
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+.mc-close {
+  background: none;
+  border: none;
+  color: rgba(255, 255, 255, 0.4);
+  font-size: 14px;
+  cursor: pointer;
+  padding: 2px 6px;
+  border-radius: 4px;
+  line-height: 1;
+}
+.mc-close:hover {
+  color: #fff;
+  background: rgba(255, 255, 255, 0.1);
+}
+
+.mc-section {
+  padding: 8px 14px 10px;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.05);
+}
+.mc-section:last-child { border-bottom: none; }
+
+.mc-section-label {
+  color: rgba(74, 240, 192, 0.5);
+  font-size: 9px;
+  text-transform: uppercase;
+  letter-spacing: 1px;
+  margin-bottom: 8px;
+}
+
+.mc-conn-list, .mc-suggest-list {
+  max-height: 200px;
+  overflow-y: auto;
+}
+.mc-conn-list::-webkit-scrollbar, .mc-suggest-list::-webkit-scrollbar { width: 3px; }
+.mc-conn-list::-webkit-scrollbar-thumb, .mc-suggest-list::-webkit-scrollbar-thumb {
+  background: rgba(74, 240, 192, 0.15);
+  border-radius: 2px;
+}
+
+.mc-conn-item, .mc-suggest-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 6px 8px;
+  border-radius: 5px;
+  margin-bottom: 4px;
+  transition: background 0.15s ease;
+}
+.mc-conn-item:hover {
+  background: rgba(74, 240, 192, 0.06);
+}
+.mc-suggest-item:hover {
+  background: rgba(123, 92, 255, 0.06);
+}
+
+.mc-conn-info, .mc-suggest-info {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+}
+.mc-conn-label, .mc-suggest-label {
+  display: block;
+  color: var(--color-text, #ccc);
+  font-size: 11px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.mc-conn-meta, .mc-suggest-meta {
+  display: block;
+  color: rgba(255, 255, 255, 0.3);
+  font-size: 9px;
+  margin-top: 1px;
+}
+
+.mc-conn-actions {
+  display: flex;
+  gap: 4px;
+  flex-shrink: 0;
+  margin-left: 8px;
+}
+
+.mc-btn {
+  background: none;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  color: rgba(255, 255, 255, 0.5);
+  cursor: pointer;
+  border-radius: 4px;
+  font-size: 12px;
+  padding: 2px 6px;
+  line-height: 1;
+  transition: all 0.15s ease;
+}
+.mc-btn-nav:hover {
+  border-color: #4af0c0;
+  color: #4af0c0;
+  background: rgba(74, 240, 192, 0.08);
+}
+.mc-btn-remove:hover {
+  border-color: #ff4466;
+  color: #ff4466;
+  background: rgba(255, 68, 102, 0.08);
+}
+.mc-btn-add {
+  border-color: rgba(123, 92, 255, 0.3);
+  color: rgba(123, 92, 255, 0.7);
+}
+.mc-btn-add:hover {
+  border-color: #7b5cff;
+  color: #7b5cff;
+  background: rgba(123, 92, 255, 0.12);
+}
+
+.mc-empty {
+  color: rgba(255, 255, 255, 0.25);
+  font-size: 11px;
+  font-style: italic;
+  padding: 4px 0;
+}