@simbimbo/memory-ocmemog 0.1.4 → 0.1.6

package/brain/runtime/memory/provenance.py

@@ -106,6 +106,16 @@ def normalize_metadata(metadata: Optional[Dict[str, Any]], *, source: Optional[s
         "derived_from_promotion_id",
         "derived_via",
         "kind",
+        "memory_status",
+        "superseded_by",
+        "supersedes",
+        "duplicate_of",
+        "duplicate_candidates",
+        "contradicts",
+        "contradiction_candidates",
+        "contradiction_status",
+        "canonical_reference",
+        "supersession_recommendation",
     ):
         if raw.get(key) is not None and provenance.get(key) is None:
             provenance[key] = raw.get(key)
@@ -177,6 +187,20 @@ def apply_links(reference: str, metadata: Optional[Dict[str, Any]]) -> None:
         _link_once(reference, "candidate", f"candidate:{provenance['derived_from_candidate_id']}")
     if provenance.get("derived_from_promotion_id"):
         _link_once(reference, "promotion", f"promotions:{provenance['derived_from_promotion_id']}")
+    if provenance.get("superseded_by"):
+        _link_once(reference, "superseded_by", str(provenance.get("superseded_by")))
+    if provenance.get("supersedes"):
+        _link_once(reference, "supersedes", str(provenance.get("supersedes")))
+    if provenance.get("duplicate_of"):
+        _link_once(reference, "duplicate_of", str(provenance.get("duplicate_of")))
+    for candidate in provenance.get("duplicate_candidates") or []:
+        _link_once(reference, "duplicate_candidate", str(candidate))
+    for target in provenance.get("contradicts") or []:
+        _link_once(reference, "contradicts", str(target))
+    for target in provenance.get("contradiction_candidates") or []:
+        _link_once(reference, "contradiction_candidate", str(target))
+    if provenance.get("canonical_reference"):
+        _link_once(reference, "canonical", str(provenance.get("canonical_reference")))
 
 
 def update_memory_metadata(reference: str, updates: Dict[str, Any]) -> Optional[Dict[str, Any]]:
@@ -201,6 +225,34 @@ def update_memory_metadata(reference: str, updates: Dict[str, Any]) -> Optional[
     return merged
 
 
+def force_update_memory_metadata(reference: str, updates: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    table, sep, raw_id = reference.partition(":")
+    if not sep or table not in _MEMORY_TABLES or not raw_id.isdigit():
+        return None
+    conn = store.connect()
+    try:
+        row = conn.execute(f"SELECT metadata_json FROM {table} WHERE id = ?", (int(raw_id),)).fetchone()
+        if not row:
+            return None
+        current = _load_json(row["metadata_json"], {})
+        provenance_meta = current.get("provenance") if isinstance(current.get("provenance"), dict) else {}
+        for key, value in updates.items():
+            if value is None or value == "":
+                provenance_meta.pop(key, None)
+            else:
+                provenance_meta[key] = value
+        current["provenance"] = provenance_meta
+        conn.execute(
+            f"UPDATE {table} SET metadata_json = ? WHERE id = ?",
+            (json.dumps(current, ensure_ascii=False), int(raw_id)),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+    apply_links(reference, current)
+    return current
+
+
 def fetch_reference(reference: str) -> Optional[Dict[str, Any]]:
     prefix, sep, raw_id = reference.partition(":")
     if not sep or not prefix:

package/brain/runtime/memory/retrieval.py

@@ -1,19 +1,57 @@
 from __future__ import annotations
 
+from datetime import datetime, timezone
 from typing import Dict, List, Any, Iterable, Tuple
 
+import json
+
 from brain.runtime.instrumentation import emit_event
 from brain.runtime import state_store
 from brain.runtime.memory import memory_links, provenance, store, vector_index
 
 
+def _tokenize(text: str) -> List[str]:
+    return [token for token in "".join(ch.lower() if ch.isalnum() else " " for ch in (text or "")).split() if token]
+
+
 def _match_score(text: str, query: str) -> float:
-    if not text:
+    if not text or not query:
         return 0.0
     text_l = text.lower()
     query_l = query.lower()
     if query_l in text_l:
         return 1.0
+    query_tokens = set(_tokenize(query_l))
+    if not query_tokens:
+        return 0.0
+    text_tokens = set(_tokenize(text_l))
+    if not text_tokens:
+        return 0.0
+    overlap = len(query_tokens & text_tokens) / max(1, len(query_tokens))
+    return round(min(0.95, overlap * 0.85), 3)
+
+
+def _recency_score(timestamp: str | None) -> float:
+    if not timestamp:
+        return 0.0
+    parsed = None
+    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%dT%H:%M:%S.%f"):
+        try:
+            parsed = datetime.strptime(timestamp, fmt).replace(tzinfo=timezone.utc)
+            break
+        except ValueError:
+            continue
+    if parsed is None:
+        return 0.0
+    age_days = max(0.0, (datetime.now(timezone.utc) - parsed).total_seconds() / 86400.0)
+    if age_days <= 1:
+        return 0.2
+    if age_days <= 7:
+        return 0.15
+    if age_days <= 30:
+        return 0.08
+    if age_days <= 180:
+        return 0.03
     return 0.0
 
 
@@ -31,6 +69,31 @@ def _empty_results() -> Dict[str, List[Dict[str, Any]]]:
     return {bucket: [] for bucket in MEMORY_BUCKETS}
 
 
+def _parse_metadata(raw: Any) -> Dict[str, Any]:
+    if isinstance(raw, dict):
+        return raw
+    try:
+        return json.loads(raw or "{}")
+    except Exception:
+        return {}
+
+
+def _governance_state(metadata: Dict[str, Any]) -> tuple[str, Dict[str, Any]]:
+    preview = provenance.preview_from_metadata(metadata)
+    prov = metadata.get("provenance") if isinstance(metadata.get("provenance"), dict) else {}
+    state = {
+        "memory_status": prov.get("memory_status") or metadata.get("memory_status") or "active",
+        "superseded_by": prov.get("superseded_by") or metadata.get("superseded_by"),
+        "supersedes": prov.get("supersedes") or metadata.get("supersedes"),
+        "duplicate_of": prov.get("duplicate_of") or metadata.get("duplicate_of"),
+        "contradicts": prov.get("contradicts") or metadata.get("contradicts") or [],
+        "contradiction_status": prov.get("contradiction_status") or metadata.get("contradiction_status"),
+        "canonical_reference": prov.get("canonical_reference") or metadata.get("canonical_reference"),
+        "provenance_preview": preview,
+    }
+    return str(state["memory_status"] or "active"), state
+
+
 def retrieve(prompt: str, limit: int = 5, categories: Iterable[str] | None = None) -> Dict[str, List[Dict[str, Any]]]:
     emit_event(state_store.reports_dir() / "brain_memory.log.jsonl", "brain_memory_retrieval_start", status="ok")
     emit_event(state_store.reports_dir() / "brain_memory.log.jsonl", "brain_memory_retrieval_rank_start", status="ok")
@@ -39,10 +102,7 @@ def retrieve(prompt: str, limit: int = 5, categories: Iterable[str] | None = Non
     results = _empty_results()
     selected_categories = tuple(dict.fromkeys(category for category in (categories or MEMORY_BUCKETS) if category in MEMORY_BUCKETS))
 
-    # reinforcement lookup (by memory_reference)
-    reinf_rows = conn.execute(
-        "SELECT memory_reference, reward_score, confidence FROM experiences",
-    ).fetchall()
+    reinf_rows = conn.execute("SELECT memory_reference, reward_score, confidence FROM experiences").fetchall()
     reinforcement: Dict[str, Dict[str, float]] = {}
     for row in reinf_rows:
         reference = str(row[0] or "")
@@ -57,66 +117,72 @@ def retrieve(prompt: str, limit: int = 5, categories: Iterable[str] | None = Non
         current["reward_score"] = float(current.get("reward_score") or 0.0) / count
         current["confidence"] = float(current.get("confidence") or 0.0) / count
 
-    def score_record(content: str, memory_ref: str, promo_conf: float) -> float:
+    semantic_scores: Dict[str, float] = {}
+    if prompt.strip():
+        for item in vector_index.search_memory(prompt, limit=max(limit * 6, 20)):
+            source_type = item.get("source_type") or "knowledge"
+            source_id = str(item.get("source_id") or "")
+            if source_type in selected_categories and source_id:
+                semantic_scores[f"{source_type}:{source_id}"] = float(item.get("score") or 0.0)
+
+    def score_record(*, content: str, memory_ref: str, promo_conf: float, timestamp: str | None) -> tuple[float, Dict[str, float]]:
         keyword = _match_score(content, prompt)
+        semantic = float(semantic_scores.get(memory_ref, 0.0))
         reinf = reinforcement.get(memory_ref, {})
-        reinf_score = float(reinf.get("reward_score", 0.0)) * 0.5
-        promo_score = float(promo_conf) * 0.3
-        return round(keyword + reinf_score + promo_score, 3)
-
-    for table, key in [(bucket, bucket) for bucket in selected_categories]:
+        reinf_score = float(reinf.get("reward_score", 0.0)) * 0.35
+        promo_score = float(promo_conf) * 0.2
+        recency = _recency_score(timestamp)
+        score = round((keyword * 0.45) + (semantic * 0.35) + reinf_score + promo_score + recency, 3)
+        return score, {
+            "keyword": round(keyword, 3),
+            "semantic": round(semantic, 3),
+            "reinforcement": round(reinf_score, 3),
+            "promotion": round(promo_score, 3),
+            "recency": round(recency, 3),
+        }
+
+    for table in selected_categories:
+        candidates: Dict[str, Dict[str, Any]] = {}
         try:
             rows = conn.execute(
-                f"SELECT id, content, confidence, metadata_json FROM {table} ORDER BY id DESC LIMIT ?",
-                (limit * 10,),
+                f"SELECT id, timestamp, content, confidence, metadata_json FROM {table} ORDER BY id DESC LIMIT ?",
+                (max(limit * 20, 50),),
             ).fetchall()
         except Exception:
             continue
         for row in rows:
-            content = row["content"] if isinstance(row, dict) else row[1]
-            if not _match_score(content, prompt):
-                continue
+            content = row["content"] if isinstance(row, dict) else row[2]
             mem_ref = f"{table}:{row[0]}"
-            promo_conf = row["confidence"] if isinstance(row, dict) else row[2]
-            metadata = provenance.fetch_reference(mem_ref)
-            results[key].append({
-                "content": content,
-                "score": score_record(content, mem_ref, promo_conf),
-                "memory_reference": mem_ref,
-                "links": memory_links.get_memory_links(mem_ref),
-                "provenance_preview": (metadata or {}).get("provenance_preview") or provenance.preview_from_metadata((metadata or {}).get("metadata")),
-            })
-
-        results[key] = sorted(results[key], key=lambda x: x["score"], reverse=True)[:limit]
-
-    if prompt.strip() and all(not results.get(bucket) for bucket in selected_categories):
-        semantic = vector_index.search_memory(prompt, limit=limit)
-        for item in semantic:
-            source_type = item.get("source_type") or "knowledge"
-            if source_type not in selected_categories:
-                continue
-            try:
-                row = conn.execute(
-                    f"SELECT id, content, confidence, metadata_json FROM {source_type} WHERE id=?",
-                    (int(item.get("source_id") or 0),),
-                ).fetchone()
-            except Exception:
+            keyword = _match_score(content, prompt)
+            semantic = float(semantic_scores.get(mem_ref, 0.0))
+            if prompt.strip() and keyword <= 0.0 and semantic <= 0.0:
                 continue
-            if not row:
+            promo_conf = row["confidence"] if isinstance(row, dict) else row[3]
+            timestamp = row["timestamp"] if isinstance(row, dict) else row[1]
+            raw_metadata = row["metadata_json"] if isinstance(row, dict) else row[4]
+            metadata_payload = _parse_metadata(raw_metadata)
+            memory_status, governance = _governance_state(metadata_payload)
+            if memory_status in {"superseded", "duplicate"}:
                 continue
-            content = row["content"] if isinstance(row, dict) else row[1]
-            mem_ref = f"{source_type}:{row[0]}"
-            promo_conf = row["confidence"] if isinstance(row, dict) else row[2]
             metadata = provenance.fetch_reference(mem_ref)
-            results[source_type].append({
+            score, signals = score_record(content=content, memory_ref=mem_ref, promo_conf=promo_conf, timestamp=timestamp)
+            if memory_status == "contested":
+                score = round(max(0.0, score - 0.15), 3)
+                signals["contradiction_penalty"] = 0.15
+            selected_because = max(signals, key=signals.get) if signals else "keyword"
+            candidates[mem_ref] = {
                 "content": content,
-                "score": score_record(content, mem_ref, promo_conf),
+                "score": score,
                 "memory_reference": mem_ref,
                 "links": memory_links.get_memory_links(mem_ref),
-                "provenance_preview": (metadata or {}).get("provenance_preview") or provenance.preview_from_metadata((metadata or {}).get("metadata")),
-            })
-        for bucket in selected_categories:
-            results[bucket] = sorted(results[bucket], key=lambda x: x["score"], reverse=True)[:limit]
+                "provenance_preview": (metadata or {}).get("provenance_preview") or governance.get("provenance_preview") or provenance.preview_from_metadata((metadata or {}).get("metadata")),
+                "retrieval_signals": signals,
+                "selected_because": selected_because,
+                "timestamp": timestamp,
+                "memory_status": memory_status,
+                "governance": governance,
+            }
+        results[table] = sorted(candidates.values(), key=lambda x: x["score"], reverse=True)[:limit]
 
     conn.close()
     emit_event(state_store.reports_dir() / "brain_memory.log.jsonl", "brain_memory_retrieval_rank_complete", status="ok")

package/brain/runtime/memory/vector_index.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+import hashlib
 import json
 import math
+import re
 import threading
 from typing import Any, Dict, List, Iterable
 
@@ -22,6 +24,9 @@ EMBEDDING_TABLES: tuple[str, ...] = (
 )
 _REBUILD_LOCK = threading.Lock()
 _WRITE_CHUNK_SIZE = 64
+_EMBEDDING_TEXT_LIMIT = 8000
+_HTML_TAG_RE = re.compile(r"<[^>]+>")
+_WHITESPACE_RE = re.compile(r"\s+")
 
 
 def _ensure_vector_table(conn) -> None:
@@ -94,30 +99,66 @@ def insert_memory(memory_id: int, content: str, confidence: float, *, source_typ
     store.submit_write(_write, timeout=30.0)
 
 
-def _load_table_rows(table: str, *, limit: int | None = None, descending: bool = False) -> List[Dict[str, Any]]:
+def _load_table_rows(table: str, *, limit: int | None = None, descending: bool = False, missing_only: bool = False) -> List[Dict[str, Any]]:
     conn = store.connect()
     try:
         order = "DESC" if descending else "ASC"
+        where = ""
+        params: list[Any] = []
+        if missing_only:
+            where = " WHERE CAST(id AS TEXT) NOT IN (SELECT source_id FROM vector_embeddings WHERE source_type = ?)"
+            params.append(table)
         if limit is None:
             rows = conn.execute(
-                f"SELECT id, content, confidence, metadata_json FROM {table} ORDER BY id {order}",
+                f"SELECT id, content, confidence, metadata_json FROM {table}{where} ORDER BY id {order}",
+                tuple(params),
             ).fetchall()
         else:
             rows = conn.execute(
-                f"SELECT id, content, confidence, metadata_json FROM {table} ORDER BY id {order} LIMIT ?",
-                (limit,),
+                f"SELECT id, content, confidence, metadata_json FROM {table}{where} ORDER BY id {order} LIMIT ?",
+                tuple(params + [limit]),
             ).fetchall()
     finally:
         conn.close()
     return [dict(row) for row in rows]
 
 
+def _embedding_input(text: str, *, table: str = "knowledge") -> str:
+    cleaned = _HTML_TAG_RE.sub(" ", text)
+    cleaned = _WHITESPACE_RE.sub(" ", cleaned).strip()
+    lowered = cleaned.lower()
+    artifactish = (
+        "| chunk " in lowered
+        or ".sql" in lowered
+        or "topology/" in lowered
+        or cleaned.count("),(") >= 8
+    )
+    if table == "knowledge" and artifactish:
+        return cleaned[:500]
+    if table == "knowledge" and len(cleaned) > 9000:
+        return cleaned[:1000]
+    if table == "reflections" and len(cleaned) > 8000:
+        return cleaned[:1200]
+    if len(cleaned) > 20000:
+        return cleaned[:2000]
+    if len(cleaned) > 12000:
+        return cleaned[:4000]
+    return cleaned[:_EMBEDDING_TEXT_LIMIT]
+
+
 def _prepare_embedding_rows(rows: Iterable[Dict[str, Any]], *, table: str) -> List[Dict[str, Any]]:
     prepared: List[Dict[str, Any]] = []
+    embedding_cache: Dict[str, List[float] | None] = {}
     for row in rows:
         content = str(row.get("content") or "")
         redacted_content, changed = redaction.redact_text(content)
-        embedding = embedding_engine.generate_embedding(redacted_content)
+        embedding_input = _embedding_input(redacted_content, table=table)
+        cache_key = hashlib.sha256(embedding_input.encode("utf-8", errors="ignore")).hexdigest()
+        if cache_key in embedding_cache:
+            embedding = embedding_cache[cache_key]
+        else:
+            embedding = embedding_engine.generate_embedding(embedding_input)
+            embedding_cache[cache_key] = embedding
         if not embedding:
             continue
         try:
@@ -213,6 +254,27 @@ def rebuild_vector_index(*, tables: Iterable[str] | None = None) -> int:
     return count
 
 
+def backfill_missing_vectors(*, tables: Iterable[str] | None = None, limit_per_table: int | None = None) -> int:
+    emit_event(LOGFILE, "brain_memory_vector_backfill_start", status="ok")
+    if not _REBUILD_LOCK.acquire(blocking=False):
+        emit_event(LOGFILE, "brain_memory_vector_backfill_complete", status="skipped", reason="already_running")
+        return 0
+    count = 0
+    try:
+        requested_tables = [table for table in (tables or EMBEDDING_TABLES) if table in EMBEDDING_TABLES]
+        for table in requested_tables:
+            prepared = _prepare_embedding_rows(
+                _load_table_rows(table, limit=limit_per_table, missing_only=True),
+                table=table,
+            )
+            for offset in range(0, len(prepared), _WRITE_CHUNK_SIZE):
+                count += _write_embedding_chunk(table, prepared[offset: offset + _WRITE_CHUNK_SIZE])
+    finally:
+        _REBUILD_LOCK.release()
+    emit_event(LOGFILE, "brain_memory_vector_backfill_complete", status="ok", indexed=count)
+    return count
+
+
 def search_memory(query: str, limit: int = 5) -> List[Dict[str, Any]]:
     emit_event(LOGFILE, "brain_memory_vector_search_start", status="ok")
     conn = store.connect()

package/docs/notes/2026-03-18-memory-repair-and-backfill.md

@@ -0,0 +1,70 @@
+# 2026-03-18 — Memory repair, integrity cleanup, and backfill tooling
+
+## Summary
+This pass focused on turning `ocmemog` from a noisy/fragile memory stack into a more repairable and laptop-safe system. The work addressed:
+- bad default vector rebuild behavior
+- misleading health/compat signals
+- missing `memory_reference` writer debt
+- poor freshness summaries
+- lack of an incremental vector backfill path
+- battery-unfriendly defaults in the sidecar launcher
+
+## Changes landed
+
+### Embedding and rebuild behavior
+- Fixed the vector reindex entrypoint so it defaults to provider-backed Ollama embeddings instead of silently rebuilding weak hash/simple vectors.
+- Confirmed local Ollama embeddings (`nomic-embed-text:latest`) are available and produce 768-dim vectors.
+- Added a new incremental repair path:
+  - `backfill_missing_vectors()` in `brain/runtime/memory/vector_index.py`
+  - `scripts/ocmemog-backfill-vectors.py`
+- This gives a non-destructive, table-by-table, chunkable way to backfill missing vectors without requiring a full destructive rebuild.
+
+### Integrity and writer correctness
+- Fixed `record_reinforcement()` so new `experiences` rows preserve a deterministic `memory_reference`.
+- Added repair support for legacy rows missing `memory_reference`.
+- Ran integrity repair and backfilled `1807` missing references.
+- Fixed duplicate promotion integrity reporting so grouped duplicate counts are reported accurately.
+
+### Health and output quality
+- Fixed sidecar compat/health reporting so provider-backed embeddings do not falsely report local hash fallback warnings.
+- Cleaned freshness summaries so placeholder content like `promoted`, `candidate_promoted`, `summary`, and `No local memory summary available` do not pollute advisories.
+- Junk-only rows now surface as `(needs summary cleanup)` instead of pretending they contain a meaningful summary.
+
+### Laptop/battery-aware behavior
+- Added battery-aware defaults to `scripts/ocmemog-sidecar.sh`.
+- `OCMEMOG_LAPTOP_MODE=auto|ac|battery` now controls watcher/ingest aggressiveness.
+- On battery the sidecar uses slower polling, smaller batches, and disables sentiment reinforcement by default.
+
+## Current integrity state
+After writer/reference repair:
+- `missing_memory_reference` debt is cleared
+- remaining integrity issue is primarily vector backlog:
+  - `vector_missing:19935`
+
+Observed coverage snapshot during staged backfill work:
+- `knowledge`: 15999 rows, 0 vectors
+- `runbooks`: 179 rows, 152 vectors
+- `lessons`: 76 rows, 76 vectors
+- `directives`: 233 rows, 206 vectors
+- `reflections`: 3460 rows, 83 vectors
+- `tasks`: 505 rows, 0 vectors
+
+## Why backlog remains
+The remaining `vector_missing` debt is mostly historical backlog rather than an active write-path failure. Existing new writes can index correctly; the old corpus simply was never fully rebuilt under the corrected provider-backed embedding path.
+
+## Recommended staged follow-up
+For laptop-friendly backlog burn-down, use staged backfills in roughly this order:
+1. directives
+2. tasks
+3. runbooks
+4. lessons
+5. reflections
+6. knowledge last
+
+## Commits from this sweep
+- `f3d3dd9` — fix: default vector reindex to ollama embeddings
+- `759d23d` — feat: add battery-aware sidecar defaults
+- `4a102eb` — fix: clean memory freshness summaries
+- `9ee7966` — fix: report duplicate promotion counts accurately
+- `8704db9` — fix: preserve and repair experience memory references
+- `5dc3cb9` — feat: add incremental vector backfill tooling

package/docs/notes/local-model-role-matrix-2026-03-18.md

@@ -0,0 +1,50 @@
+# Local model role matrix — 2026-03-18
+
+Purpose: document which installed local model is best suited for which `ocmemog` task so background cognition can be smarter without putting heavy/slow models on every path.
+
+Installed local models observed:
+- `phi3:latest`
+- `qwen2.5:7b`
+- `llama3.1:8b`
+- embeddings: `nomic-embed-text:latest`
+
+## Intended decision areas
+- unresolved-state rewrite
+- lesson extraction
+- ponder/reflection shaping
+- cluster recommendation wording
+- fallback/speed path
+
+## Bakeoff results
+
+### Unresolved-state rewrite
+- **Winner:** `qwen2.5:7b`
+- Why: cleanest concise rewrite, best instruction-following, least rambling.
+- Notes:
+  - `phi3:latest` tended to be verbose and occasionally hallucination-prone.
+  - `llama3.1:8b` produced one outright unusable response ("None found...").
+
+### Lesson extraction
+- **Winner:** `qwen2.5:7b`
+- Strong alternate: `llama3.1:8b`
+- Why: `qwen2.5:7b` produced the clearest operational lesson with good cause/effect preservation.
+- Notes:
+  - `phi3:latest` was weaker and more generic.
+
+### Cluster insight / recommendation shaping
+- **Winner:** `qwen2.5:7b`
+- Why: best structured output, least fluff, most concrete recommendation wording.
+- Notes:
+  - `llama3.1:8b` was decent but more wordy/stylized.
+  - `phi3:latest` timed out or underperformed on this task.
+
+## Recommended model-role split
+- embeddings: `nomic-embed-text:latest`
+- fast fallback cognition: `phi3:latest`
+- default structured memory refinement / ponder model: `qwen2.5:7b`
+- richer optional background cognition: `llama3.1:8b`
+
+## Operational recommendation
+- Keep `OCMEMOG_OLLAMA_MODEL=phi3:latest` for lightweight local fallback behavior.
+- Set `OCMEMOG_PONDER_MODEL=qwen2.5:7b` for unresolved-state rewrite, lesson extraction, and cluster recommendation shaping.
+- Consider `llama3.1:8b` for optional deeper background cognition passes where latency is acceptable.

package/docs/usage.md

@@ -23,7 +23,7 @@ Manual watcher:
 ```bash
 # defaults to ~/.openclaw/workspace/memory/transcripts if not set
 export OCMEMOG_TRANSCRIPT_DIR="$HOME/.openclaw/workspace/memory/transcripts"
-export OCMEMOG_INGEST_ENDPOINT="http://127.0.0.1:17890/memory/ingest"
+export OCMEMOG_INGEST_ENDPOINT="http://127.0.0.1:17891/memory/ingest"
 ./scripts/ocmemog-transcript-watcher.sh
 ```
 
@@ -34,11 +34,13 @@ export OCMEMOG_TRANSCRIPT_WATCHER=true
 ./scripts/ocmemog-sidecar.sh
 ```
 
+On macOS laptops, the launcher defaults to `OCMEMOG_LAPTOP_MODE=auto`, which detects battery power and uses lower-impact watcher settings automatically. Override with `OCMEMOG_LAPTOP_MODE=ac` for wall-power behavior or `OCMEMOG_LAPTOP_MODE=battery` to force conservative mode.
+
 Useful environment variables:
 
 ```bash
 export OCMEMOG_HOST=127.0.0.1
-export OCMEMOG_PORT=17890
+export OCMEMOG_PORT=17891
 export OCMEMOG_STATE_DIR=/path/to/state
 export OCMEMOG_DB_PATH=/path/to/brain_memory.sqlite3
 export OCMEMOG_MEMORY_MODEL=gpt-4o-mini
@@ -62,26 +64,26 @@ Default state location in this repo is `.ocmemog-state/`.
 Health:
 
 ```bash
-curl http://127.0.0.1:17890/healthz
+curl http://127.0.0.1:17891/healthz
 ```
 
 Realtime metrics + events:
 
 ```bash
-curl http://127.0.0.1:17890/metrics
-curl http://127.0.0.1:17890/events
+curl http://127.0.0.1:17891/metrics
+curl http://127.0.0.1:17891/events
 ```
 
 Dashboard:
 
 ```bash
-open http://127.0.0.1:17890/dashboard
+open http://127.0.0.1:17891/dashboard
 ```
 
 Search:
 
 ```bash
-curl -s http://127.0.0.1:17890/memory/search \
+curl -s http://127.0.0.1:17891/memory/search \
   -H 'content-type: application/json' \
   -d '{"query":"deploy risk","limit":5,"categories":["knowledge","tasks"]}'
 ```
@@ -95,7 +97,7 @@ If `OCMEMOG_API_TOKEN` is set, include the header:
 Get by reference:
 
 ```bash
-curl -s http://127.0.0.1:17890/memory/get \
+curl -s http://127.0.0.1:17891/memory/get \
   -H 'content-type: application/json' \
   -d '{"reference":"knowledge:12"}'
 ```
@@ -103,7 +105,7 @@ curl -s http://127.0.0.1:17890/memory/get \
 Fetch linked context (transcript snippet):
 
 ```bash
-curl -s http://127.0.0.1:17890/memory/context \
+curl -s http://127.0.0.1:17891/memory/context \
   -H 'content-type: application/json' \
   -d '{"reference":"knowledge:12","radius":10}'
 ```
@@ -117,7 +119,7 @@ Helper script:
 Run pondering (writes summaries into reflections):
 
 ```bash
-curl -s http://127.0.0.1:17890/memory/ponder \
+curl -s http://127.0.0.1:17891/memory/ponder \
   -H 'content-type: application/json' \
   -d '{"max_items":5}'
 ```
@@ -125,13 +127,13 @@ curl -s http://127.0.0.1:17890/memory/ponder \
 Fetch latest ponder recommendations:
 
 ```bash
-curl -s http://127.0.0.1:17890/memory/ponder/latest?limit=5
+curl -s http://127.0.0.1:17891/memory/ponder/latest?limit=5
 ```
 
 Ingest content:
 
 ```bash
-curl -s http://127.0.0.1:17890/memory/ingest \
+curl -s http://127.0.0.1:17891/memory/ingest \
   -H 'content-type: application/json' \
   -d '{"content":"remember this","kind":"memory","memory_type":"knowledge"}'
 ```
@@ -139,7 +141,7 @@ curl -s http://127.0.0.1:17890/memory/ingest \
 Ingest with context anchors (links to chat/transcript):
 
 ```bash
-curl -s http://127.0.0.1:17890/memory/ingest \
+curl -s http://127.0.0.1:17891/memory/ingest \
   -H 'content-type: application/json' \
   -d '{
         "content":"remember this",
@@ -157,7 +159,7 @@ curl -s http://127.0.0.1:17890/memory/ingest \
 Distill recent experiences:
 
 ```bash
-curl -s http://127.0.0.1:17890/memory/distill \
+curl -s http://127.0.0.1:17891/memory/distill \
   -H 'content-type: application/json' \
   -d '{"limit":10}'
 ```

package/index.ts

@@ -1,6 +1,6 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/memory-core";
 
-const DEFAULT_ENDPOINT = "http://127.0.0.1:17890";
+const DEFAULT_ENDPOINT = "http://127.0.0.1:17891";
 const DEFAULT_TIMEOUT_MS = 30_000;
 
 type PluginConfig = {