@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/compose.yaml

@@ -0,0 +1,227 @@
+name: openmem
+
+# Memory provider stack (Hindsight by default) and the project/Obsidian indexer.
+# Set HINDSIGHT_ENV_FILE to use an env file other than ~/.config/hindsight/hindsight.env.
+#
+# Provider selection is by compose profile:
+#   - litellm and hindsight carry the profile "hindsight" (and "notebooklm", which needs them). litellm also carries
+#     its own profile "litellm", so a provider other than Hindsight can run the stack LiteLLM as its model gateway
+#     (mem0: providers/mem0/compose.yaml publishes it on loopback; docs/mem0.md "Models through the stack LiteLLM").
+#   - indexer and indexer-state-init have no profile and no hard provider dependency; they start for every provider.
+#   - Another provider ships providers/<id>/compose.yaml (see providers/_template/compose.yaml) with its own
+#     profile, and layers over this file: docker compose -f compose.yaml -f providers/<id>/compose.yaml --profile <id> up -d
+# Compose starts no profiled service unless a profile is enabled, so the plain `docker compose up -d` of the README
+# needs COMPOSE_PROFILES=hindsight in .env (or --profile hindsight). Note that a --profile flag replaces
+# COMPOSE_PROFILES rather than adding to it; name every profile you want on the command line.
+
+# Shared build for the indexer and its state-volume init step.
+x-indexer-build: &indexer-build
+  build:
+    context: .
+    dockerfile: indexer/Dockerfile
+
+services:
+  # OpenAI-compatible proxy in front of the model server. Hindsight calls it at http://litellm:4000/v1 with the
+  # fixed aliases memory-retain, memory-reflect, memory-consolidate. Routes live in LITELLM_CONFIG (set by scripts/setup.sh).
+  # Internal network only under Hindsight: nothing is published to the host. The "litellm" profile runs it without
+  # Hindsight; providers/mem0/compose.yaml then publishes it on 127.0.0.1 and refuses to start without a master key.
+  litellm:
+    profiles: ["hindsight", "notebooklm", "litellm"]
+    image: ghcr.io/berriai/litellm:v1.106.6
+    command: ["--config", "/app/config.yaml", "--port", "4000"]
+    env_file: ${LITELLM_ENV_FILE:-${HOME}/.config/hindsight/litellm.env}
+    volumes:
+      - ${LITELLM_CONFIG:?run scripts/setup.sh}:/app/config.yaml:ro
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:4000/health/liveliness', timeout=5)"]
+      interval: 15s
+      timeout: 10s
+      retries: 10
+      start_period: 30s
+
+  hindsight:
+    profiles: ["hindsight", "notebooklm"]
+    depends_on:
+      litellm:
+        condition: service_healthy
+    # Pinned to the digest running before the pin (org.opencontainers.image.version 1.0.0). Bump deliberately.
+    image: ghcr.io/vectorize-io/hindsight@sha256:a88678c038b0e4340822b02a5efc566c56d8176b5bffa731bc433fd37f978e4c
+    # Embedded Postgres needs more than Docker's 64 MB default /dev/shm.
+    shm_size: 1g
+    env_file: ${HINDSIGHT_ENV_FILE:-${HOME}/.config/hindsight/hindsight.env}
+    ports:
+      # Host ports from .env (HINDSIGHT_PORT, HINDSIGHT_CP_PORT); defaults 8888 and 9999.
+      - "127.0.0.1:${HINDSIGHT_PORT:-8888}:8888"
+      - "127.0.0.1:${HINDSIGHT_CP_PORT:-9999}:9999"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    volumes:
+      # Named volume: the image's hindsight user (UID 1000) owns it on first use, unlike a host bind mount.
+      - hindsight-data:/home/hindsight/.pg0
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8888/health', timeout=5)"]
+      interval: 15s
+      timeout: 10s
+      retries: 10
+      start_period: 60s
+
+  indexer:
+    <<: *indexer-build
+    image: openmem-indexer:local
+    # Host UID/GID from .env, written by scripts/setup.sh. The image needs no passwd entry for this user.
+    user: "${HOST_UID:?run scripts/setup.sh}:${HOST_GID:?run scripts/setup.sh}"
+    # Same absolute paths inside the container so bank and document IDs match host paths.
+    # Read-only: the indexer reads repositories and writes only its state volume below. Tree-sitter outlines
+    # need no writes, and CodeGraph's .codegraph/ writes are gone.
+    # Secret paths under $HOME are masked by compose.override.yaml, generated by scripts/gen-masks.sh (required).
+    volumes:
+      - ${HOME}:${HOME}:ro
+      # Writable state (state.json, lock). Its mount point is inside the read-only $HOME mount.
+      - indexer-state:${HOME}/.cache/hindsight-project-index
+    environment:
+      HOME: ${HOME}
+      HINDSIGHT_URL: http://hindsight:8888
+    depends_on:
+      # Soft: waits for Hindsight to be healthy when its profile is active and is ignored otherwise (other providers
+      # add their own dependency in providers/<id>/compose.yaml). Unlike a hard dependency, an unhealthy Hindsight
+      # only logs a warning; the indexer starts anyway and its watcher retries.
+      hindsight:
+        condition: service_healthy
+        required: false
+      indexer-state-init:
+        condition: service_completed_successfully
+    restart: unless-stopped
+
+  # Named volumes are created root-owned. This one-off root step gives the state volume to the host UID, then exits.
+  indexer-state-init:
+    <<: *indexer-build
+    image: openmem-indexer:local
+    user: "0:0"
+    entrypoint: ["sh", "-c", "chown ${HOST_UID:?run scripts/setup.sh}:${HOST_GID:?run scripts/setup.sh} /state"]
+    volumes:
+      - indexer-state:/state
+    restart: "no"
+
+  # Opt-in: docker compose --profile ollama up -d ollama. Used when the host has no Ollama; LiteLLM reaches it at
+  # http://ollama:11434 on the compose network. Port 11434 is published on loopback so the wizard can probe and pull.
+  ollama:
+    profiles: ["ollama"]
+    image: ollama/ollama:latest
+    ports:
+      - "127.0.0.1:11434:11434"
+    volumes:
+      - ollama-data:/root/.ollama
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "ollama list >/dev/null 2>&1 || exit 1"]
+      interval: 15s
+      timeout: 10s
+      retries: 10
+      start_period: 20s
+
+  # Opt-in: docker compose --profile notebooklm up -d notebooklm. Syncs into notebooklm::* banks on the active MEMORY_SINK.
+  # Login is on the host (README "NotebookLM"); the storage under ~/.config/notebooklm is bind-mounted read-write.
+  notebooklm:
+    profiles: ["notebooklm"]
+    build:
+      context: .
+      dockerfile: sync/Dockerfile
+    image: openmem-notebooklm:local
+    # Host UID/GID from .env, written by scripts/setup.sh; the bind-mounted login storage must stay host-owned.
+    user: "${HOST_UID:?run scripts/setup.sh}:${HOST_GID:?run scripts/setup.sh}"
+    environment:
+      HINDSIGHT_URL: http://hindsight:8888
+      MEMORY_SINK: ${MEMORY_SINK:-hindsight}
+      MEMORY_API_URL: ${MEMORY_API_URL:-}
+      NOTEBOOKLM_HOME: /data/notebooklm
+      NOTEBOOKLM_STATE: /data/state/state.json
+    volumes:
+      - type: bind
+        source: ${HOME}/.config/notebooklm
+        target: /data/notebooklm
+        bind:
+          create_host_path: false
+      # Per-machine override (only the keys you change). Create the file before starting; compose does not create it.
+      - type: bind
+        source: ${NOTEBOOKLM_OVERRIDE:-${HOME}/.config/hindsight/notebooklm.yml}
+        target: /etc/notebooklm/override.yml
+        read_only: true
+        bind:
+          create_host_path: false
+      # Writable sync state (state.json). The image creates it 0777, so Docker copies that mode into the new volume.
+      - notebooklm-state:/data/state
+    depends_on:
+      hindsight:
+        condition: service_healthy
+        required: false
+    restart: unless-stopped
+
+  # Opt-in: docker compose --profile context-proxy up -d context-proxy. LiteLLM in front of Anthropic for coding
+  # agents: compresses large tool results and trims long sessions (docs/context-proxy.md). Separate from the litellm
+  # service and outside the hindsight profile, so Hindsight's own model traffic never passes through it.
+  context-proxy:
+    profiles: ["context-proxy"]
+    # Dev build on purpose: v1.109.0-dev.1 is the only LiteLLM release with PR #41522, the ChatGPT/Codex
+    # subscription pass-through (/backend-api/codex/{endpoint}) that routes Codex here; stable releases
+    # (v1.106.6, v1.108.0-rc.1) lack it. The litellm service above stays on stable. Move to the first stable
+    # release that contains #41522, then rerun proxy/tests/image/run.py.
+    image: ghcr.io/berriai/litellm:v1.109.0-dev.1
+    command: ["--config", "/app/proxy/config.yaml", "--port", "4000"]
+    # LITELLM_MASTER_KEY (and any provider keys for extra routes). Written by install-coding-agent.
+    env_file: ${CONTEXT_PROXY_ENV_FILE:-${HOME}/.config/personal-memory/context-proxy.env}
+    # Host UID/GID from .env, written by scripts/setup.sh; the context store stays host-owned (docs/context-store.md).
+    user: "${HOST_UID:?run scripts/setup.sh}:${HOST_GID:?run scripts/setup.sh}"
+    ports:
+      - "127.0.0.1:${CONTEXT_PROXY_PORT:-4100}:4000"
+    environment:
+      HOME: /tmp
+      PYTHONDONTWRITEBYTECODE: "1"
+      OPENMEM_STATE_DIR: /state
+      HINDSIGHT_URL: ${CONTEXT_PROXY_HINDSIGHT_URL:-http://hindsight:8888}
+      CONTEXT_PROXY_ENABLED: ${CONTEXT_PROXY_ENABLED:-1}
+      # From config.toml [context_proxy] trim_at_tokens / trim_to_fraction / compress_over_tokens / standing_instruction / chars_per_token, [compaction] max_chars / recall
+      # and [context_store] ttl_days / embedding_model / embedding_timeout_s / embedding_max_chars,
+      # written into .env by scripts/setup.mjs and install-coding-agent; a shell export overrides .env.
+      # CONTEXT_TRIM_AT_TOKENS stays empty when unset, so the proxy picks the threshold by model.
+      CONTEXT_TRIM_AT_TOKENS: ${CONTEXT_TRIM_AT_TOKENS:-}
+      CONTEXT_TRIM_TO_FRACTION: ${CONTEXT_TRIM_TO_FRACTION:-0.3}
+      CONTEXT_COMPRESS_OVER_TOKENS: ${CONTEXT_COMPRESS_OVER_TOKENS:-4000}
+      CONTEXT_COMPACTION_MAX_CHARS: ${CONTEXT_COMPACTION_MAX_CHARS:-12000}
+      CONTEXT_COMPACTION_RECALL: ${CONTEXT_COMPACTION_RECALL:-1}
+      CONTEXT_STANDING_INSTRUCTION: ${CONTEXT_STANDING_INSTRUCTION:-1}
+      CONTEXT_CHARS_PER_TOKEN: ${CONTEXT_CHARS_PER_TOKEN:-2.5}
+      # Session databases (docs/context-store.md): [context_store] ttl_days and embedding_model. Vectors are off while
+      # CONTEXT_EMBEDDING_MODEL is empty; the embeddings URL is the container's view of an OpenAI-compatible
+      # /embeddings endpoint (Ollama on the host by default). CONTEXT_EMBEDDING_API_KEY, if needed, goes in the env file.
+      CONTEXT_STORE_TTL_DAYS: ${CONTEXT_STORE_TTL_DAYS:-30}
+      CONTEXT_EMBEDDING_MODEL: ${CONTEXT_EMBEDDING_MODEL:-}
+      CONTEXT_EMBEDDING_URL: ${CONTEXT_PROXY_EMBEDDING_URL:-http://host.docker.internal:11434/v1}
+      CONTEXT_EMBEDDING_TIMEOUT_S: ${CONTEXT_EMBEDDING_TIMEOUT_S:-30}
+      CONTEXT_EMBEDDING_MAX_CHARS: ${CONTEXT_EMBEDDING_MAX_CHARS:-4000}
+    volumes:
+      - ./proxy:/app/proxy:ro
+      # Create it first (mode 700, host-owned); compose would otherwise create a root-owned directory.
+      - type: bind
+        source: ${OPENMEM_STATE_DIR:-${HOME}/.local/share/openmem}/context
+        target: /state/context
+        bind:
+          create_host_path: false
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:4000/health/liveliness', timeout=5)"]
+      interval: 15s
+      timeout: 10s
+      retries: 10
+      start_period: 30s
+
+volumes:
+  hindsight-data:
+  indexer-state:
+  notebooklm-state:
+  ollama-data:

package/config/coding-agent.json

@@ -0,0 +1,13 @@
+{
+  "serverMode": "self-hosted",
+  "apiUrl": "http://127.0.0.1:8888",
+  "optInOnly": true,
+  "optInPaths": [],
+  "mapPathToBank": {},
+  "notebooklmAccess": {
+    "enabled": false,
+    "banks": [
+      "*"
+    ]
+  }
+}

package/config/hindsight.env.example

@@ -0,0 +1,26 @@
+# Copy to ~/.config/hindsight/hindsight.env and edit. The real file lives outside the repository;
+# compose.yaml reads it from there (or $HINDSIGHT_ENV_FILE).
+# Docker reaches host services at host.docker.internal.
+# All LLM calls go to the LiteLLM proxy (compose service `litellm`). Models are chosen in config/litellm.*.yaml.
+# scripts/setup.sh --migrate-env writes HINDSIGHT_API_LLM_API_KEY from ~/.config/hindsight/litellm.env.
+HINDSIGHT_API_LLM_PROVIDER=openai
+HINDSIGHT_API_LLM_BASE_URL=http://litellm:4000/v1
+HINDSIGHT_API_LLM_MODEL=memory-reflect
+HINDSIGHT_API_RETAIN_LLM_MODEL=memory-retain
+HINDSIGHT_API_REFLECT_LLM_MODEL=memory-reflect
+HINDSIGHT_API_CONSOLIDATION_LLM_MODEL=memory-consolidate
+HINDSIGHT_API_MENTAL_MODEL_REFRESH_LLM_MODEL=memory-reflect
+HINDSIGHT_API_LLM_API_KEY=replace-me
+HINDSIGHT_API_EMBEDDINGS_PROVIDER=local
+HINDSIGHT_API_RERANKER_PROVIDER=local
+HINDSIGHT_API_WORKER_ID=hindsight-personal
+HINDSIGHT_API_SKIP_LLM_VERIFICATION=true
+HINDSIGHT_API_LLM_MAX_CONCURRENT=1
+HINDSIGHT_API_LLM_TIMEOUT=300
+HINDSIGHT_API_LLM_MAX_RETRIES=1
+
+# verbatim: store chunk text as-is; LLM only extracts entities/time/location (faster than concise).
+HINDSIGHT_API_RETAIN_EXTRACTION_MODE=verbatim
+HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS=16384
+HINDSIGHT_API_REFLECT_MAX_COMPLETION_TOKENS=2048
+HINDSIGHT_API_CONSOLIDATION_MAX_COMPLETION_TOKENS=2048

package/config/index.yml

@@ -0,0 +1,54 @@
+# Project indexer config. The indexer reads the first of: --config PATH, $HINDSIGHT_INDEX_CONFIG,
+# ~/.config/hindsight/index.yml, this file. A per-machine file replaces this one entirely; keys it omits
+# take the built-in values, which match this file. Paths are absolute or start with ~ (a bare ~ is null
+# in YAML, which also means home under roots[].path).
+
+# Git repositories: walk each root to `depth` levels and index the outermost repositories found.
+roots:
+  - path: ~
+    depth: 3
+
+# Extra repositories, indexed even when no root reaches them.
+repos:
+  - ~/.config/nvim
+
+vaults:
+  auto: true     # any folder within a root's depth that contains .obsidian/
+  paths: []      # extra vault folders
+
+# Markdown folders without .obsidian (watched like vaults; banks default to <kind>::<slug>).
+notes:
+  paths: []
+papers:
+  paths: []   # e.g. Zotero Better BibTeX markdown export, arXiv notes, PDF-adjacent .md
+bookmarks:
+  paths: []   # e.g. browser export (Linkwarden, Karakeep, manual markdown dumps)
+
+# Optional: pull RSS/arXiv/OpenAlex into out_dir; indexer watches out_dir as kind `feed`.
+feeds:
+  out_dir: ~/.local/share/personal-memory/feeds
+  rss: []
+  openalex_queries: []
+
+# Glob patterns on absolute paths. A source that matches is skipped.
+exclude: []
+
+# Absolute path prefix -> Hindsight bank id. The longest matching prefix wins; applies to repos and vaults.
+# Unmatched repositories fall back to ~/.config/personal-memory/coding-agent.json mapPathToBank,
+# then the legacy ~/.hindsight/coding-agent.json mapping, then coding-agent::<repository-name>.
+banks:
+  ~/Documents/sample-project: coding-agent::documents-sample-project
+  # ~/Zotero/export-md: papers::zotero
+  # ~/Readwise/Full-Sync: readwise::full-sync
+  # ~/.local/share/personal-memory/feeds: feed::cache
+
+# Largest file indexed, in kilobytes (1 KB = 1000 bytes).
+max_file_kb: 128
+
+# Directory names never descended into (dot-prefixed directories are always skipped).
+skip_dirs: [.cache, .codegraph, .decision, .git, .next, .tasks, .venv, build, dist, node_modules, target, vendor]
+
+# Watcher timings, in seconds. Environment variables POLL_SECONDS, VAULT_QUIET_SECONDS and RELIST_SECONDS override them.
+poll_seconds: 60
+vault_quiet_seconds: 30
+relist_seconds: 600

package/config/litellm.lemond.yaml

@@ -0,0 +1,40 @@
+# LiteLLM routes for Hindsight, backend: lemond on this machine (llama.cpp).
+# Selected by scripts/setup.sh when MEMORY_BACKEND=lemond (the default). See README "Model configuration".
+# Hindsight asks for the fixed aliases below; change the model behind an alias here, not in Hindsight.
+# Every alias runs Nemotron 3.5 Bolt E4B (JSON output and tool calls checked 2026-10-23) with thinking disabled:
+# thinking adds tokens before the answer, and at max_tokens 200 can leave content empty.
+# Passed through to lemond's chat template. Hindsight's per-request reasoning_effort cannot override it.
+model_list:
+  - model_name: memory-retain
+    litellm_params:
+      model: openai/Nemotron-3.5-Bolt-E4B-GGUF
+      api_base: http://host.docker.internal:13305/v1
+      max_tokens: 4096
+      timeout: 300
+      api_key: os.environ/LEMOND_API_KEY
+      extra_body:
+        chat_template_kwargs:
+          enable_thinking: false
+  - model_name: memory-reflect
+    litellm_params:
+      model: openai/Nemotron-3.5-Bolt-E4B-GGUF
+      api_base: http://host.docker.internal:13305/v1
+      max_tokens: 4096
+      timeout: 300
+      api_key: os.environ/LEMOND_API_KEY
+      extra_body:
+        chat_template_kwargs:
+          enable_thinking: false
+  - model_name: memory-consolidate
+    litellm_params:
+      model: openai/Nemotron-3.5-Bolt-E4B-GGUF
+      api_base: http://host.docker.internal:13305/v1
+      max_tokens: 4096
+      timeout: 300
+      api_key: os.environ/LEMOND_API_KEY
+      extra_body:
+        chat_template_kwargs:
+          enable_thinking: false
+
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY

package/config/litellm.ollama.yaml

@@ -0,0 +1,33 @@
+# LiteLLM routes for Hindsight, backend: Ollama on a laptop.
+# Selected by scripts/setup.sh when MEMORY_BACKEND=ollama. See README "Model configuration".
+# Hindsight asks for the fixed aliases below; change the model behind an alias here, not in Hindsight.
+# Every alias disables Gemma thinking: thinking adds tokens before the answer, and at max_tokens 200 can leave content empty.
+# Sent as Ollama's top-level "think": false. Overrides Hindsight's per-request reasoning_effort.
+model_list:
+  - model_name: memory-retain
+    litellm_params:
+      model: ollama_chat/gemma4:e2b
+      api_base: http://host.docker.internal:11434
+      max_tokens: 4096
+      timeout: 300
+      extra_body:
+        think: false
+  - model_name: memory-reflect
+    litellm_params:
+      model: ollama_chat/gemma4:e4b
+      api_base: http://host.docker.internal:11434
+      max_tokens: 4096
+      timeout: 300
+      extra_body:
+        think: false
+  - model_name: memory-consolidate
+    litellm_params:
+      model: ollama_chat/gemma4:e2b
+      api_base: http://host.docker.internal:11434
+      max_tokens: 4096
+      timeout: 300
+      extra_body:
+        think: false
+
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY

package/config/notebooklm.yml

@@ -0,0 +1,33 @@
+# NotebookLM sync (opt-in: docker compose --profile notebooklm up -d notebooklm).
+# Per-machine override: ~/.config/hindsight/notebooklm.yml. Put only the keys you change there;
+# mappings merge key by key, lists and scalars replace the shipped value.
+
+enabled: false
+
+# client: unofficial notebooklm-py client, uses the browser login stored in ~/.config/notebooklm.
+# enterprise: documented NotebookLM Enterprise REST API (notebook list only; see README).
+backend: client
+
+interval_minutes: 60
+
+# Hindsight bank per notebook: <bank_prefix>::<slug of notebook title>.
+bank_prefix: notebooklm
+
+# Title globs (fnmatch, case-insensitive). include empty means every notebook.
+include_notebooks: []
+exclude_notebooks: []
+
+include:
+  notes: true
+  sources: true   # source list, URLs, full text and guide summary where the client returns them
+  chats: false    # saved chat question/answer history
+
+client:
+  # Empty uses NOTEBOOKLM_HOME (set to /data/notebooklm in the container).
+  storage_path: ""
+
+enterprise:
+  project_number: ""          # numeric project number, required for backend: enterprise
+  location: global            # global | us | eu
+  service_account_file: ""    # path inside the container; empty uses Application Default Credentials
+  notebook_limit: 500         # listRecentlyViewed page size, 1..500

package/config/openmem.toml.example

@@ -0,0 +1,124 @@
+# Mise-like declarative config for the openmem meta wizard.
+#
+#   mkdir -p ~/.config/personal-memory
+#   cp config/openmem.toml.example ~/.config/personal-memory/config.toml
+#   $EDITOR ~/.config/personal-memory/config.toml
+#   ./setup --yes
+#
+# Precedence (highest wins): CLI flags → environment variables →
+#   ~/.config/personal-memory/config.toml → ./personal-memory.toml (stack root) →
+#   ~/.config/hindsight/wizard.conf (last configure run).
+#
+# Provider-native settings (mem0 cloud, Hindsight product UI, etc.) stay in those tools;
+# this file only describes how this machine runs the shared stack.
+
+[memory]
+provider = "hindsight"
+
+[stack]
+project = "openmem"
+api_port = 8888
+control_plane_port = 9999
+
+# Default wizard action when ./setup runs non-interactively without --up/--down
+[wizard]
+action = "configure" # configure | up | down
+
+# LLM routing for Hindsight (LiteLLM → lemond/Ollama/custom/Meridian). Not lemond's own config.
+[model]
+backend = "lemond" # lemond | ollama | custom | meridian (Claude subscription, docs/meridian-litellm.md)
+retain = "Gemma-4-E2B-it-GGUF"
+reflect = ""       # empty = shipped memory-reflect route
+api_base = ""      # custom backend only
+
+[model.lemond]
+host = "http://127.0.0.1:13305"
+
+[model.ollama]
+host = "http://127.0.0.1:11434"
+
+# meridian backend only: Meridian's URL as seen from this host. The wizard does not run Meridian.
+# [model.meridian]
+# host = "http://127.0.0.1:3456"
+
+# Coding-agent wiring, written by `install-coding-agent`.
+# integration: "openmem" = OpenMem session hooks; "provider" = the provider's own plugin
+# (Hindsight: @vectorize-io/hindsight-coding-agents). The two hook sets are exclusive.
+[agents]
+integration = "openmem"
+
+# Local LiteLLM context proxy (`install-coding-agent --context-proxy`). When enabled,
+# Claude Code's ANTHROPIC_BASE_URL points at http://127.0.0.1:<port>.
+# trim_at_tokens / compress_over_tokens (and [compaction] max_chars) reach the proxy
+# container through the stack .env (written by ./setup and install-coding-agent) and the
+# OpenCode 2 plugin; the env vars CONTEXT_TRIM_AT_TOKENS, CONTEXT_COMPRESS_OVER_TOKENS,
+# CONTEXT_TRIM_TO_FRACTION, CONTEXT_STANDING_INSTRUCTION, CONTEXT_CHARS_PER_TOKEN and CONTEXT_COMPACTION_MAX_CHARS
+# override them.
+[context_proxy]
+# enabled = false           # master switch; agents without a key below follow it (unset: opencode2 on, others off)
+port = 4100
+trim_at_tokens = 120000     # trim a session once its request exceeds this many tokens
+trim_to_fraction = 0.3      # a trim keeps older in-turn exchanges while the request is under this fraction of trim_at_tokens (0 < x < 1)
+compress_over_tokens = 4000 # compress tool results larger than this
+standing_instruction = true # constant system-prompt note telling the agent to search trimmed turns
+chars_per_token = 2.5       # token estimate before a session reports usage; reported usage calibrates it after
+
+# Session databases (sessions/<sid>.db, docs/context-store.md): every message of a trimmed session.
+# ttl_days: delete sessions idle longer than this, checked at proxy / MCP start at most once a day (0 = keep).
+# embedding_model: OpenAI-compatible embedding model for hybrid smart_compact_search; empty = vectors off.
+# The stack ships no embedding route; e.g. `ollama pull nomic-embed-text` and set it here.
+# embedding_url: that endpoint as this host sees it (the proxy container uses CONTEXT_PROXY_EMBEDDING_URL).
+# embedding_timeout_s: seconds per row of a background embeddings call (a batch of n rows gets n times this).
+#   Batches start at 4 rows, double while calls finish well inside the timeout and halve on a failure.
+# embedding_max_chars: characters of each row's head that are embedded; the vector covers only that part.
+#   4000 fits nomic-embed-text's 2048-token context; raise it only for a model with a longer one.
+[context_store]
+ttl_days = 30
+embedding_model = ""
+embedding_url = "http://127.0.0.1:11434/v1"
+embedding_timeout_s = 30
+embedding_max_chars = 4000
+
+# Optional per-agent overrides (written by the wizard and `openmem context on|off --agents`).
+# claude-code and opencode1 go through the context-proxy service, which install-coding-agent starts
+# when one of them is on and stops when none is. opencode2 trims in its own plugin (no service;
+# CONTEXT_PROXY_ENABLED overrides it); with neither its key nor `enabled` set it is on.
+# codex is accepted but not routed yet.
+# [context_proxy.agents]
+# claude-code = true
+# opencode1 = true
+# codex = false
+# opencode2 = true
+
+# native (OpenCode 2 only): when OpenCode compacts a session, OpenMem's plugin supplies the
+# smart_compact_search pointer + recall as the summary instead of a model call.
+# false leaves compaction to OpenCode.
+# max_chars: cap on the recall text placed after a trim or compaction pointer.
+[compaction]
+native = true
+max_chars = 12000
+# recall = true             # provider recall in the trim pointer, framed as untrusted data (env CONTEXT_COMPACTION_RECALL)
+
+# Optional indexer defaults (wizard may still prompt interactively)
+# [[index.roots]]
+# path = "~"
+# depth = 3
+
+# Mise-style named tasks (run via ./pm <name>)
+[tasks.configure]
+description = "Secrets, index sources, build images, compose up"
+
+[tasks.up]
+description = "Start stack using existing config"
+
+[tasks.down]
+description = "docker compose down for this project"
+
+[tasks.doctor]
+description = "Validate memory setup on this machine"
+
+# Provider-native options live in their own tables, not under [model].
+# mem0 is URL-only: point at a self-hosted REST server (not https://api.mem0.ai).
+# [memory.mem0]
+# api_url = "http://127.0.0.1:18888"
+# env_file = "~/.config/personal-memory/mem0.env"

package/docs/OPENMEM.md

@@ -0,0 +1,23 @@
+# OpenMem
+
+**OpenMem** is the product name for this repository (formerly *personal-memory*).
+
+For the product idea — memory interface for coding agents, providers, `memory_*`, banks, formats — start with **[Concepts](https://bcmyguest.github.io/openmem/docs/concepts/)**.
+
+## CLI
+
+```sh
+npx @bcmyguest/openmem
+openmem setup
+openmem doctor
+```
+
+Bins: `openmem`, `openmem-setup`, `openmem-mcp`, `openmem-install-mcp`, `openmem-install-coding-agent`, `openmem-switch-provider`, `openmem-notebooklm-mcp`, `openmem-cognee-mcp`.
+
+Machine config paths under `~/.config/personal-memory/` and `~/.config/hindsight/` stay as-is for now so existing installs keep working. Installers rewrite leftover `personal-memory` MCP server entries to `openmem`.
+
+## Repo
+
+- GitHub: [bcmyguest/openmem](https://github.com/bcmyguest/openmem)
+- Docs: [site](https://bcmyguest.github.io/openmem/) · [Concepts](https://bcmyguest.github.io/openmem/docs/concepts/) · [Quickstart](https://bcmyguest.github.io/openmem/docs/getting-started/)
+- npm: `openmem` (package formerly `personal-memory`)