@simbimbo/memory-ocmemog 0.1.4

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## 0.1.4 — 2026-03-18
+
+Package ownership + runtime safety release.
+
+### Highlights
+- Renamed npm package to `@simbimbo/memory-ocmemog` so it can be published under Steven's own npm scope
+- Updated installer/docs to use the `@simbimbo` package while keeping plugin id `memory-ocmemog` unchanged
+- Preserved the OpenClaw runtime safety hardening from 0.1.3 (sync-safe ingest + auto-hydration opt-in guard)
+
+## 0.1.3 — 2026-03-18
+
+OpenClaw runtime safety hardening release.
+
+### Highlights
+- Made `before_message_write` continuity ingest sync-safe for OpenClaw's synchronous hook contract
+- Disabled automatic prompt hydration by default unless `OCMEMOG_AUTO_HYDRATION=true` is explicitly set
+- Kept sidecar-backed memory search/ingest/checkpoint flows active while guarding against context-window blowups from prepended continuity wrappers
+- Added startup logging so hosts can see when auto hydration is intentionally disabled
+
+## 0.1.2 — 2026-03-17
+
+Continuity hydration hardening release.
+
+### Highlights
+- Prevented recursive re-ingest of auto-hydrated continuity wrappers into conversational state
+- Kept short confirmation replies like `ok`, `yes`, and `sure` compact in `latest_user_ask` / `latest_user_intent`
+- Changed hydration to prefer unresolved assistant commitments only
+- Ignored oversized/noisy checkpoint summaries during hydration selection
+- Normalized sender envelopes, reply tags, and polluted multi-timestamp wrapper text before they could pollute state
+- Added self-healing cleanup for legacy poisoned turns/checkpoints during refresh
+- Hardened `memory_links` unique-index setup against duplicate legacy rows
+- Added `.DS_Store` ignore hygiene for the repo
+
+### Included commits
+- `231cfcb` — fix: harden continuity hydration against recursive contamination
+- `3db6891` — fix: keep short reply intent compact in hydration state
+- `fe49663` — fix: prefer unresolved assistant commitments in hydration
+- `74a44fc` — fix: drop oversized checkpoint summaries from hydration
+- `4b89fc1` — chore: ignore macOS Finder metadata files
+
+## 0.1.1 — 2026-03-16
+
+Publish-prep release.
+
+### Highlights
+- Cleaned package metadata for public release
+- Corrected repository and homepage links to the actual `simbimbo/ocmemog` repo
+- Removed "scaffold" positioning from release-facing package metadata
+- Tightened README wording around current status and install flow
+- Excluded Python cache artifacts, tests, reports, and review notes from the published package
+- Verified clean package output with `npm pack --dry-run`
+- Re-ran continuity benchmark with passing score (`overall_score: 1.0`)
+
+### Intended publish command
+```bash
+clawhub publish . --slug memory-ocmemog --name "ocmemog" --version 0.1.1 --changelog "Initial public release: durable memory, transcript-backed continuity, packaging cleanup, and publish-ready metadata"
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw
+
+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.

package/README.md

@@ -0,0 +1,223 @@
+# ocmemog
+
+**ocmemog** is an advanced memory engine for OpenClaw that combines durable long-term memory, transcript-backed continuity, conversation hydration, checkpoint expansion, and pondering inside a sidecar-based plugin architecture.
+
+It is designed to go beyond simple memory search by providing:
+- **durable memory and semantic retrieval**
+- **lossless-style conversation continuity**
+- **checkpointing, branch-aware hydration, and turn expansion**
+- **transcript ingestion with anchored context recovery**
+- **pondering and reflection generation**
+
+Architecture at a glance:
+- **OpenClaw plugin (`index.ts`)** handles tools and hook integration
+- **FastAPI sidecar (`ocmemog/sidecar/`)** exposes memory and continuity APIs
+- **SQLite-backed runtime (`brain/runtime/memory/`)** powers storage, hydration, checkpoints, salience ranking, and pondering
+
+## Repo layout
+
+- `openclaw.plugin.json`, `index.ts`, `package.json`: OpenClaw plugin package and manifest.
+- `ocmemog/sidecar/`: FastAPI sidecar with `/memory/search` and `/memory/get`.
+- `brain/runtime/memory/`: copied brAIn memory package.
+- `brain/runtime/`: compatibility shims for state store, instrumentation, redaction, storage paths, and a few placeholder runtime modules needed for importability.
+- `scripts/ocmemog-sidecar.sh`: convenience launcher.
+
+## Run the sidecar
+
+```bash
+cd /path/to/ocmemog
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+./scripts/ocmemog-sidecar.sh
+
+# then open
+# http://127.0.0.1:17890/dashboard
+```
+
+## Optional: transcript watcher (auto-ingest)
+
+```bash
+# defaults to ~/.openclaw/workspace/memory/transcripts if not set
+export OCMEMOG_TRANSCRIPT_DIR="$HOME/.openclaw/workspace/memory/transcripts"
+./scripts/ocmemog-transcript-watcher.sh
+```
+
+Default bind:
+
+- endpoint: `http://127.0.0.1:17890`
+- health: `http://127.0.0.1:17890/healthz`
+
+## Continuity proof / benchmark harness
+
+Run the fixture-driven continuity benchmark:
+
+```bash
+cd /path/to/ocmemog
+./.venv/bin/python scripts/ocmemog-continuity-benchmark.py \
+  --fixture tests/fixtures/continuity_benchmark.json \
+  --report reports/continuity-benchmark-latest.json
+```
+
+This exercises:
+- restart/recovery hydration from persisted SQLite state
+- long-thread + ambiguous reply continuity
+- salience-ranked checkpoint expansion
+- salience-ranked turn expansion
+
+A passing run writes a JSON report with per-scenario checks and an `overall_score` that must meet the configured `continuity_bar`.
+
+Optional environment variables:
+
+- `OCMEMOG_HOST`
+- `OCMEMOG_PORT`
+- `OCMEMOG_STATE_DIR` (defaults to `<repo>/.ocmemog-state`)
+- `OCMEMOG_DB_PATH`
+- `OCMEMOG_MEMORY_MODEL` (default: `gpt-4o-mini`)
+- `OCMEMOG_OPENAI_API_KEY` (required for model-backed distill)
+- `OCMEMOG_OPENAI_API_BASE` (default: `https://api.openai.com/v1`)
+- `OCMEMOG_OPENAI_EMBED_MODEL` (default: `text-embedding-3-small`)
+- `BRAIN_EMBED_MODEL_LOCAL` (`simple` by default)
+- `BRAIN_EMBED_MODEL_PROVIDER` (`openai` to enable provider embeddings)
+- `OCMEMOG_TRANSCRIPT_WATCHER` (`true` to auto-start transcript watcher inside the sidecar)
+- `OCMEMOG_TRANSCRIPT_ROOTS` (comma-separated allowed roots for transcript context retrieval; default: `~/.openclaw/workspace/memory`)
+- `OCMEMOG_API_TOKEN` (optional; if set, requests must include `x-ocmemog-token` or `Authorization: Bearer ...`)
+- `OCMEMOG_AUTO_HYDRATION` (`true` to re-enable prompt-time continuity prepending; defaults to `false` as a safety guard until the host runtime is verified not to persist prepended context into session history)
+- `OCMEMOG_USE_OLLAMA` (`true` to use Ollama for distill/inference)
+- `OCMEMOG_OLLAMA_HOST` (default: `http://127.0.0.1:11434`)
+- `OCMEMOG_OLLAMA_MODEL` (default: `phi3:latest`)
+- `OCMEMOG_OLLAMA_EMBED_MODEL` (default: `nomic-embed-text:latest`)
+- `OCMEMOG_PROMOTION_THRESHOLD` (default: `0.5`)
+- `OCMEMOG_DEMOTION_THRESHOLD` (default: `0.2`)
+- `OCMEMOG_PONDER_ENABLED` (default: `true`)
+- `OCMEMOG_PONDER_MODEL` (default: `OCMEMOG_MEMORY_MODEL`)
+- `OCMEMOG_LESSON_MINING_ENABLED` (default: `true`)
+
+## Security
+
+- Sidecar binds to **127.0.0.1** by default. Keep it local unless you add auth + firewall rules.
+- If you expose the sidecar, set `OCMEMOG_API_TOKEN` and pass the header `x-ocmemog-token`.
+
+## One‑shot installer (macOS / local dev)
+
+```bash
+./scripts/install-ocmemog.sh
+```
+
+Optional target checkout directory:
+
+```bash
+./scripts/install-ocmemog.sh /custom/path/ocmemog
+```
+
+Optional prereq auto-install on macOS/Homebrew systems:
+
+```bash
+OCMEMOG_INSTALL_PREREQS=true ./scripts/install-ocmemog.sh
+```
+
+Quick help:
+
+```bash
+./scripts/install-ocmemog.sh --help
+```
+
+This installer will try to:
+- clone/update the repo when a custom target directory is provided
+- create `.venv`
+- install Python requirements
+- install/enable the OpenClaw plugin when the `openclaw` CLI is available
+- install/load LaunchAgents via `scripts/ocmemog-install.sh`
+- pull required local Ollama models when Ollama is already installed
+- validate `/healthz`
+
+Notes:
+- If `OCMEMOG_INSTALL_PREREQS=true` and Homebrew is present, the installer will try to install missing `ollama` and `ffmpeg` automatically.
+- If Ollama is not installed and prereq auto-install is off or unavailable, the installer warns and continues; local model support will remain unavailable until Ollama is installed.
+- If package install is unavailable in the local OpenClaw build, the installer falls back to local-path plugin install.
+- Advanced flags are available for local debugging/CI (`--skip-plugin-install`, `--skip-launchagents`, `--skip-model-pulls`, `--endpoint`, `--repo-url`).
+
+## LaunchAgents (macOS)
+
+Templates are included under `scripts/launchagents/`:
+- `com.openclaw.ocmemog.sidecar.plist`
+- `com.openclaw.ocmemog.ponder.plist`
+- `com.openclaw.ocmemog.guard.plist`
+
+You can load them with:
+```bash
+launchctl bootstrap gui/$UID scripts/launchagents/com.openclaw.ocmemog.sidecar.plist
+launchctl bootstrap gui/$UID scripts/launchagents/com.openclaw.ocmemog.ponder.plist
+launchctl bootstrap gui/$UID scripts/launchagents/com.openclaw.ocmemog.guard.plist
+```
+
+## Recent changes
+
+### 0.1.4 (unreleased / current main)
+
+Package ownership + runtime safety release:
+- Publish package under `@simbimbo/memory-ocmemog` instead of the unauthorized `@openclaw` scope
+- Keep `memory-ocmemog` as the plugin id for OpenClaw config and enable flows
+- Make `before_message_write` ingest sync-safe for OpenClaw's synchronous hook contract
+- Default auto prompt hydration to opt-in via `OCMEMOG_AUTO_HYDRATION=true`
+- Preserve prior continuity self-healing and polluted-wrapper cleanup behavior
+
+## Release prep / publish
+
+Current intended ClawHub publish command:
+
+```bash
+clawhub publish . --slug memory-ocmemog --name "ocmemog" --version 0.1.4 --changelog "Package ownership fix: publish under @simbimbo scope plus runtime safety hardening for sync-safe ingest and auto-hydration guard"
+```
+
+## Install from npm (after publish)
+
+```bash
+openclaw plugins install @simbimbo/memory-ocmemog
+openclaw plugins enable memory-ocmemog
+```
+
+## Enable in OpenClaw (local dev)
+
+Add the plugin to your OpenClaw config. The key setting is selecting `memory-ocmemog` in the `memory` slot and pointing the plugin entry at this repo.
+
+```yaml
+plugins:
+  load:
+    paths:
+      - /path/to/ocmemog
+  slots:
+    memory: memory-ocmemog
+  entries:
+    memory-ocmemog:
+      enabled: true
+      config:
+        endpoint: http://127.0.0.1:17890
+        timeoutMs: 30000
+```
+
+Development install:
+
+```bash
+openclaw plugins install -l /path/to/ocmemog
+openclaw plugins enable memory-ocmemog
+```
+
+If your local OpenClaw build also documents a separate `memory.backend` setting, keep that at its current default unless your build explicitly requires a plugin-backed override. The slot selection above is what activates this plugin.
+
+## Current status
+
+ocmemog is usable today for local OpenClaw installs that want a stronger memory layer with durable recall and transcript-backed continuity.
+
+What is working now:
+- Search/get against the local SQLite-backed memory store
+- Transcript ingestion and anchored context recovery
+- Continuity hydration, checkpoint expansion, and salience-ranked expansion flows
+- Local sidecar deployment for macOS/OpenClaw development setups
+
+Current limitations before broader public rollout:
+- Some advanced inference- and embedding-dependent paths still depend on environment configuration and may degrade to simpler local behavior if provider access is unavailable
+- Packaging and install UX are aimed primarily at power users and local developers today
+- Public release/distribution metadata is still being tightened up
+
+When a richer path is unavailable, the sidecar is designed to fail soft with explicit warnings rather than crash.

package/brain/__init__.py

@@ -0,0 +1 @@
+"""Local compatibility package for the copied brAIn memory runtime."""

package/brain/runtime/__init__.py

@@ -0,0 +1,13 @@
+"""Minimal runtime shims required by the copied brAIn memory package."""
+
+from . import config, inference, instrumentation, model_roles, model_router, state_store, storage_paths
+
+__all__ = [
+    "config",
+    "inference",
+    "instrumentation",
+    "model_roles",
+    "model_router",
+    "state_store",
+    "storage_paths",
+]

package/brain/runtime/config.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import os
+
+BRAIN_EMBED_MODEL_LOCAL = os.environ.get("BRAIN_EMBED_MODEL_LOCAL", "simple")
+BRAIN_EMBED_MODEL_PROVIDER = os.environ.get("BRAIN_EMBED_MODEL_PROVIDER", "")
+
+OCMEMOG_MEMORY_MODEL = os.environ.get("OCMEMOG_MEMORY_MODEL", "gpt-4o-mini")
+OCMEMOG_OPENAI_API_BASE = os.environ.get("OCMEMOG_OPENAI_API_BASE", "https://api.openai.com/v1")
+OCMEMOG_OPENAI_EMBED_MODEL = os.environ.get("OCMEMOG_OPENAI_EMBED_MODEL", "text-embedding-3-small")
+
+OCMEMOG_OLLAMA_HOST = os.environ.get("OCMEMOG_OLLAMA_HOST", "http://127.0.0.1:11434")
+OCMEMOG_OLLAMA_MODEL = os.environ.get("OCMEMOG_OLLAMA_MODEL", "phi3:latest")
+OCMEMOG_OLLAMA_EMBED_MODEL = os.environ.get("OCMEMOG_OLLAMA_EMBED_MODEL", "nomic-embed-text:latest")
+
+OCMEMOG_PROMOTION_THRESHOLD = float(os.environ.get("OCMEMOG_PROMOTION_THRESHOLD", "0.5"))
+OCMEMOG_DEMOTION_THRESHOLD = float(os.environ.get("OCMEMOG_DEMOTION_THRESHOLD", "0.2"))
+
+OCMEMOG_PONDER_ENABLED = os.environ.get("OCMEMOG_PONDER_ENABLED", "true")
+OCMEMOG_PONDER_MODEL = os.environ.get("OCMEMOG_PONDER_MODEL", OCMEMOG_MEMORY_MODEL)
+OCMEMOG_LESSON_MINING_ENABLED = os.environ.get("OCMEMOG_LESSON_MINING_ENABLED", "true")

package/brain/runtime/inference.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.request
+
+from brain.runtime import config, state_store
+from brain.runtime.instrumentation import emit_event
+
+LOGFILE = state_store.reports_dir() / "brain_memory.log.jsonl"
+
+
+def _infer_ollama(prompt: str, model: str | None = None) -> dict[str, str]:
+    payload = {
+        "model": model or config.OCMEMOG_OLLAMA_MODEL,
+        "prompt": prompt,
+        "stream": False,
+    }
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(f"{config.OCMEMOG_OLLAMA_HOST.rstrip('/')}/api/generate", data=data, method="POST")
+    req.add_header("Content-Type", "application/json")
+    try:
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            response = json.loads(resp.read().decode("utf-8"))
+    except Exception as exc:
+        emit_event(LOGFILE, "brain_infer_error", status="error", provider="ollama", error=str(exc))
+        return {"status": "error", "error": f"ollama_failed:{exc}"}
+    output = response.get("response")
+    if not output:
+        emit_event(LOGFILE, "brain_infer_error", status="error", provider="ollama", error="invalid_response")
+        return {"status": "error", "error": "invalid_response"}
+    return {"status": "ok", "output": str(output).strip()}
+
+
+def infer(prompt: str, provider_name: str | None = None) -> dict[str, str]:
+    if not isinstance(prompt, str) or not prompt.strip():
+        return {"status": "error", "error": "empty_prompt"}
+
+    use_ollama = os.environ.get("OCMEMOG_USE_OLLAMA", "").lower() in {"1", "true", "yes"}
+    model_override = provider_name or config.OCMEMOG_MEMORY_MODEL
+    if use_ollama or model_override.startswith("ollama:"):
+        model = model_override.split(":", 1)[-1] if model_override.startswith("ollama:") else model_override
+        return _infer_ollama(prompt, model)
+
+    api_key = os.environ.get("OCMEMOG_OPENAI_API_KEY") or os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        # fall back to local ollama if configured
+        return _infer_ollama(prompt, config.OCMEMOG_OLLAMA_MODEL)
+
+    model = model_override
+    url = f"{config.OCMEMOG_OPENAI_API_BASE.rstrip('/')}/chat/completions"
+    payload = {
+        "model": model,
+        "messages": [{"role": "user", "content": prompt}],
+        "temperature": 0.2,
+    }
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(url, data=data, method="POST")
+    req.add_header("Authorization", f"Bearer {api_key}")
+    req.add_header("Content-Type", "application/json")
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            response = json.loads(resp.read().decode("utf-8"))
+    except Exception as exc:
+        emit_event(LOGFILE, "brain_infer_error", status="error", provider="openai", error=str(exc))
+        return {"status": "error", "error": f"request_failed:{exc}"}
+
+    try:
+        output = response["choices"][0]["message"]["content"]
+    except Exception as exc:
+        emit_event(LOGFILE, "brain_infer_error", status="error", provider="openai", error=str(exc))
+        return {"status": "error", "error": "invalid_response"}
+
+    return {"status": "ok", "output": str(output).strip()}
+
+
+def parse_operator_name(text: str) -> dict[str, str] | None:
+    match = re.search(r"\bmy name is ([A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\b", text, flags=re.IGNORECASE)
+    if not match:
+        return None
+    return {"name": match.group(1)}

package/brain/runtime/instrumentation.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def emit_event(path: Path, event: str, **fields: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "event": event,
+        **fields,
+    }
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(payload, sort_keys=True) + "\n")

package/brain/runtime/memory/__init__.py

@@ -0,0 +1,13 @@
+__all__ = [
+    "store",
+    "distill",
+    "candidate",
+    "promote",
+    "retrieval",
+    "reinforcement",
+    "integrity",
+    "vector_index",
+    "context_builder",
+    "memory_taxonomy",
+    "health",
+]

package/brain/runtime/memory/api.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import json
+from typing import List, Dict, Any
+
+from brain.runtime.memory import provenance, store
+from brain.runtime.instrumentation import emit_event
+from brain.runtime.security import redaction
+
+
+def _sanitize(text: str) -> str:
+    redacted, _ = redaction.redact_text(text)
+    return redacted
+
+
+def _emit(event: str) -> None:
+    emit_event(store.state_store.reports_dir() / "brain_memory.log.jsonl", event, status="ok")
+
+
+def record_event(event_type: str, payload: str, *, source: str | None = None) -> None:
+    payload = _sanitize(payload)
+    details_json = json.dumps({"payload": payload})
+    def _write() -> None:
+        conn = store.connect()
+        try:
+            conn.execute(
+                "INSERT INTO memory_events (event_type, source, details_json, schema_version) VALUES (?, ?, ?, ?)",
+                (event_type, source, details_json, store.SCHEMA_VERSION),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    store.submit_write(_write, timeout=30.0)
+    _emit("record_event")
+
+
+def record_task(task_id: str, status: str, *, source: str | None = None) -> None:
+    status = _sanitize(status)
+    metadata_json = json.dumps({"task_id": task_id})
+    def _write() -> None:
+        conn = store.connect()
+        try:
+            conn.execute(
+                "INSERT INTO tasks (source, confidence, metadata_json, content, schema_version) VALUES (?, ?, ?, ?, ?)",
+                (source, 1.0, metadata_json, status, store.SCHEMA_VERSION),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    store.submit_write(_write, timeout=30.0)
+    _emit("record_task")
+
+
+def store_memory(
+    memory_type: str,
+    content: str,
+    *,
+    source: str | None = None,
+    metadata: Dict[str, Any] | None = None,
+    timestamp: str | None = None,
+) -> int:
+    content = _sanitize(content)
+    table = memory_type.strip().lower() if memory_type else "knowledge"
+    allowed = {"knowledge", "reflections", "directives", "tasks", "runbooks", "lessons"}
+    if table not in allowed:
+        table = "knowledge"
+    normalized_metadata = provenance.normalize_metadata(metadata, source=source)
+
+    def _write() -> int:
+        conn = store.connect()
+        try:
+            if timestamp:
+                cur = conn.execute(
+                    f"INSERT INTO {table} (source, confidence, metadata_json, content, schema_version, timestamp) VALUES (?, ?, ?, ?, ?, ?)",
+                    (source, 1.0, json.dumps(normalized_metadata, ensure_ascii=False), content, store.SCHEMA_VERSION, timestamp),
+                )
+            else:
+                cur = conn.execute(
+                    f"INSERT INTO {table} (source, confidence, metadata_json, content, schema_version) VALUES (?, ?, ?, ?, ?)",
+                    (source, 1.0, json.dumps(normalized_metadata, ensure_ascii=False), content, store.SCHEMA_VERSION),
+                )
+            conn.commit()
+            return int(cur.lastrowid)
+        finally:
+            conn.close()
+
+    last_row_id = store.submit_write(_write, timeout=30.0)
+    reference = f"{table}:{last_row_id}"
+    provenance.apply_links(reference, normalized_metadata)
+    try:
+        from brain.runtime.memory import vector_index
+
+        vector_index.insert_memory(last_row_id, content, 1.0, source_type=table)
+    except Exception as exc:
+        emit_event(store.state_store.reports_dir() / "brain_memory.log.jsonl", "store_memory_index_failed", status="error", error=str(exc), memory_type=table)
+    _emit("store_memory")
+    return last_row_id
+
+
+def record_reinforcement(task_id: str, outcome: str, note: str, *, source_module: str | None = None) -> None:
+    outcome = _sanitize(outcome)
+    note = _sanitize(note)
+    def _write() -> None:
+        conn = store.connect()
+        try:
+            conn.execute(
+                "INSERT INTO experiences (task_id, outcome, reward_score, confidence, experience_type, source_module, schema_version) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (task_id, outcome, None, 1.0, "reinforcement", source_module, store.SCHEMA_VERSION),
+            )
+            conn.execute(
+                "INSERT INTO memory_events (event_type, source, details_json, schema_version) VALUES (?, ?, ?, ?)",
+                ("reinforcement_note", source_module, json.dumps({"task_id": task_id, "note": note}), store.SCHEMA_VERSION),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    store.submit_write(_write, timeout=30.0)
+    _emit("record_reinforcement")
+
+
+def get_recent_events(limit: int = 10) -> List[Dict[str, Any]]:
+    conn = store.connect()
+    rows = conn.execute(
+        "SELECT id, timestamp, event_type, source, details_json FROM memory_events ORDER BY id DESC LIMIT ?",
+        (limit,),
+    ).fetchall()
+    conn.close()
+    return [dict(row) for row in rows]
+
+
+def get_recent_tasks(limit: int = 10) -> List[Dict[str, Any]]:
+    conn = store.connect()
+    rows = conn.execute(
+        "SELECT id, timestamp, source, confidence, metadata_json, content FROM tasks ORDER BY id DESC LIMIT ?",
+        (limit,),
+    ).fetchall()
+    conn.close()
+    return [dict(row) for row in rows]
+
+
+def get_memories(limit: int = 10) -> List[Dict[str, Any]]:
+    conn = store.connect()
+    rows = conn.execute(
+        "SELECT id, timestamp, source, confidence, metadata_json, content FROM knowledge ORDER BY id DESC LIMIT ?",
+        (limit,),
+    ).fetchall()
+    conn.close()
+    return [dict(row) for row in rows]

package/brain/runtime/memory/artifacts.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, Any
+
+from brain.runtime import state_store
+from brain.runtime.memory import store
+
+
+def _artifact_dir() -> Path:
+    path = state_store.memory_dir() / "artifacts"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def store_artifact(artifact_id: str, content: bytes, metadata: Dict[str, Any]) -> Path:
+    path = _artifact_dir() / f"{artifact_id}.bin"
+    path.write_bytes(content)
+    content_hash = str(hash(content))
+    conn = store.connect()
+    conn.execute(
+        "INSERT INTO artifacts (artifact_id, artifact_type, source_path, content_hash, metadata) VALUES (?, ?, ?, ?, ?)",
+        (artifact_id, metadata.get("artifact_type", "unknown"), metadata.get("source_path", ""), content_hash, json.dumps(metadata)),
+    )
+    conn.commit()
+    conn.close()
+    return path
+
+
+def load_artifact(artifact_id: str) -> bytes:
+    path = _artifact_dir() / f"{artifact_id}.bin"
+    return path.read_bytes()