local dev: .env for local development (gitignored)

- .env.example: template with all service URIs for local development
- LOCAL_DEV.md: guide for running poimen locally
- Production: config.yaml (SOPS-encrypted K8s ConfigMap)
- Local: .env file (gitignored, never committed)
- Application reads from ENV in both cases (K8s ConfigMap + local dotenv)
- Simplifies prod/dev: same code, different config sources

.env.example

@@ -0,0 +1,50 @@
+# Local development environment (.env file)
+# Copy to .env and fill in your local/dev URLs
+# .env is gitignored - never commit
+
+# Auth mode: jwt | apikey | none
+MEM_AUTH_MODE=none
+
+# Rate limiting
+MEM_RATE_LIMIT_INGEST=1000
+MEM_RATE_LIMIT_QUERY=10000
+MEM_IDEMPOTENCY_TTL_SECS=86400
+
+# Embeddings
+MEM_EMBEDDING_BATCH_SIZE=32
+
+# Database (local or remote)
+DATABASE_URL=postgresql://user:password@localhost:5432/memory
+
+# Downstream services - point to your local/dev endpoints
+
+# LLM Service (entity extraction, fact extraction)
+LLM_ENDPOINT=http://localhost:11434/v1/chat/completions
+LLM_API_BASE=http://localhost:11434/v1
+LLM_MODEL=qwen:7b
+LLM_TIMEOUT_SECS=60
+ENABLE_LLM_EXTRACTION=true
+
+# OpenSearch (vector store, BM25)
+OPENSEARCH_HOST=localhost:9200
+OPENSEARCH_SCHEME=http
+OPENSEARCH_VERIFY_CERTS=false
+
+# Authentik (OIDC - optional for local dev)
+AUTHENTIK_ISSUER=https://authentik.riotpiao.com/application/o/poimen/
+AUTHENTIK_CLIENT_ID=
+AUTHENTIK_CLIENT_SECRET=
+TOKEN_URL=https://authentik.riotpiao.com/application/o/token/
+AUTHENTIK_VERIFY_SSL=false
+
+# Temporal (workflow orchestration - future)
+TEMPORAL_ENDPOINT=localhost:7233
+TEMPORAL_NAMESPACE=poimen
+
+# API Gateway (route optimization - future)
+GATEWAY_URL=http://localhost:8080
+
+# Server config
+MEM_PORT=8080
+MEM_API_KEY=test-key
+MEM_HOME=/tmp

.gitea/workflows/build.yaml

@@ -26,17 +26,11 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Cargo build all
+      - name: Cargo build, test, clippy (single compile pass)
-        run: cargo build --all --verbose
+        run: |
-
+          cargo build --all --verbose
-      - name: Cargo test all
+          cargo test --all --lib --verbose 2>&1 | tail -150 || true
-        run: cargo test --all --lib --verbose 2>&1 | tail -150 || true
+          cargo clippy --all --all-targets -- -D warnings 2>&1 | tail -50 || true
-
-      - name: Cargo clippy
-        run: cargo clippy --all --all-targets -- -D warnings 2>&1 | tail -50 || true
-
-      - name: Clean build artifacts before Docker
-        run: cargo clean
 
       - name: Get short SHA
         id: sha
@@ -44,6 +38,10 @@ jobs:
 
       - name: Registry login
         run: |
+          if [ -z "${REGISTRY_USER}" ] || [ -z "${REGISTRY_TOKEN}" ]; then
+            echo "ERROR: Missing REGISTRY_USER or REGISTRY_TOKEN secrets"
+            exit 1
+          fi
           echo "${REGISTRY_TOKEN}" | docker login "${REGISTRY}" \
             --username "${REGISTRY_USER}" --password-stdin
         env:

.gitea/workflows/deploy.yaml

@@ -15,29 +15,48 @@ jobs:
     name: Tag & Push Latest
     runs-on: rust
     steps:
-      - name: Install Docker
+      - name: Install Docker and curl
-        run: apt-get update && apt-get install -y docker.io
+        run: apt-get update && apt-get install -y docker.io curl
 
-      - name: Checkout code
+      - name: Get short SHA via Gitea API
-        uses: actions/checkout@v4
-
-      - name: Get short SHA
         id: sha
-        run: echo "short_sha=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+        run: |
+          # Fetch latest commit SHA for main branch from Gitea API
+          COMMIT_SHA=$(curl -s -H "Authorization: token ${REGISTRY_TOKEN}" \
+            "https://forgejo.riotpiao.com/api/v1/repos/riotpiao-poimen/poimen-memory/commits?sha=main&limit=1" | \
+            grep -o '"sha":"[^"]*' | head -1 | cut -d'"' -f4)
+          
+          if [ -z "$COMMIT_SHA" ]; then
+            echo "ERROR: Failed to fetch commit SHA from Gitea API"
+            exit 1
+          fi
+          
+          SHORT_SHA=$(echo "$COMMIT_SHA" | cut -c1-7)
+          echo "short_sha=$SHORT_SHA" >> $GITHUB_OUTPUT
+          echo "Full SHA: $COMMIT_SHA, Short: $SHORT_SHA"
+        env:
+          REGISTRY_TOKEN: ${{ secrets.FORGEJO_REGISTRY_TOKEN }}
 
       - name: Registry login
         run: |
+          if [ -z "${REGISTRY_USER}" ] || [ -z "${REGISTRY_TOKEN}" ]; then
+            echo "ERROR: Missing REGISTRY_USER or REGISTRY_TOKEN secrets"
+            exit 1
+          fi
           echo "${REGISTRY_TOKEN}" | docker login "${REGISTRY}" \
             --username "${REGISTRY_USER}" --password-stdin
         env:
           REGISTRY_USER: ${{ secrets.FORGEJO_REGISTRY_USER }}
           REGISTRY_TOKEN: ${{ secrets.FORGEJO_REGISTRY_TOKEN }}
 
-      - name: Pull SHA image and tag as latest
+      - name: Verify SHA image exists, tag as latest
         run: |
-          docker pull "${IMAGE}:${{ steps.sha.outputs.short_sha }}" && \
+          if ! docker pull "${IMAGE}:${{ steps.sha.outputs.short_sha }}"; then
-          docker tag "${IMAGE}:${{ steps.sha.outputs.short_sha }}" "${IMAGE}:latest" && \
+            echo "ERROR: Image ${IMAGE}:${{ steps.sha.outputs.short_sha }} not found. Check build.yaml passed."
-          docker push "${IMAGE}:latest" && \
+            exit 1
+          fi
+          docker tag "${IMAGE}:${{ steps.sha.outputs.short_sha }}" "${IMAGE}:latest"
+          docker push "${IMAGE}:latest"
           echo "Tagged and pushed: ${IMAGE}:latest (from ${{ steps.sha.outputs.short_sha }})"
 
       - name: Prune images

.gitea/workflows/migrate.yaml

@@ -31,7 +31,7 @@ jobs:
           echo "Changed migrations: $CHANGED"
           echo "CHANGED_MIGRATIONS=$CHANGED" >> $GITHUB_ENV
 
-      - name: Run migrations
+      - name: Run changed migrations and verify schema
         if: env.CHANGED_MIGRATIONS != ''
         run: |
           export PGPASSWORD="${DB_PASSWORD}"
@@ -55,18 +55,27 @@ jobs:
           DB_USER: ${{ secrets.DB_USER }}
           DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
 
-      - name: Run all migrations (manual trigger)
+      - name: Run all migrations and verify schema (manual trigger)
         if: github.event_name == 'workflow_dispatch'
         run: |
           export PGPASSWORD="${DB_PASSWORD}"
 
           echo "=== Running all migrations in order ==="
+          FAILED=0
           for f in $(ls crates/mem-store/migrations/*.sql | sort); do
             echo "--- Applying: $f ---"
-            psql -h "$DB_HOST" -p "$DB_PORT" -U "$DB_USER" -d "$DB_NAME" -f "$f" 2>&1 || true
+            if ! psql -h "$DB_HOST" -p "$DB_PORT" -U "$DB_USER" -d "$DB_NAME" -f "$f" 2>&1; then
-            echo "--- Done: $f ---"
+              echo "ERROR: Migration $f failed!"
+              FAILED=1
+            else
+              echo "--- OK: $f ---"
+            fi
           done
 
+          if [ $FAILED -eq 1 ]; then
+            exit 1
+          fi
+
           echo "=== Final schema ==="
           psql -h "$DB_HOST" -p "$DB_PORT" -U "$DB_USER" -d "$DB_NAME" -c "\dt memory*"
           psql -h "$DB_HOST" -p "$DB_PORT" -U "$DB_USER" -d "$DB_NAME" -c "\d memory_entity"

LOCAL_DEV.md

@@ -0,0 +1,84 @@
+# Local Development Setup
+
+Running poimen-memory locally for development.
+
+## Quick Start
+
+1. **Copy env template**:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. **Edit `.env`** with your local endpoints:
+   ```bash
+   # Edit .env with your local/dev service URLs
+   # Example: LLM service on localhost:11434, OpenSearch on localhost:9200
+   ```
+
+3. **Run the service**:
+   ```bash
+   cargo run --release -- serve --port 8080
+   ```
+
+The application loads configuration from `.env` (via `dotenvy` or similar).
+
+## `.env` File
+
+**Location**: Project root (`.env`)
+**Status**: Gitignored - never committed
+**Template**: `.env.example` (included in repo, shows all available variables)
+
+### Key Variables
+
+```bash
+# Database
+DATABASE_URL=postgresql://user:pass@localhost:5432/memory
+
+# LLM (point to your local LLM service)
+LLM_ENDPOINT=http://localhost:11434/v1/chat/completions
+LLM_MODEL=qwen:7b
+
+# OpenSearch (local vector store)
+OPENSEARCH_HOST=localhost:9200
+
+# Auth (disabled for local dev)
+MEM_AUTH_MODE=none
+
+# API Key (test key for local dev)
+MEM_API_KEY=test-key
+```
+
+## Local Service Stack (Example)
+
+```bash
+# Terminal 1: OpenSearch
+docker run -d -p 9200:9200 -e OPENSEARCH_JAVA_OPTS="-Xms512m -Xmx512m" \
+  opensearchproject/opensearch:latest
+
+# Terminal 2: Ollama (LLM)
+ollama serve
+
+# Terminal 3: poimen-memory
+cargo run --release -- serve --port 8080
+```
+
+## Production vs Local
+
+| Aspect | Production (K8s) | Local Dev |
+|--------|-----------------|-----------|
+| **Config** | `k8s/app/config.yaml` (SOPS-encrypted) | `.env` (gitignored) |
+| **Injection** | ConfigMap via `envFrom:` | dotenv via `dotenvy` crate |
+| **Services** | Cluster-internal DNS | localhost/127.0.0.1 |
+| **Auth** | JWT (Authentik) | None (disabled) |
+| **Commit?** | Yes (encrypted) | No (gitignored) |
+
+## Switching to Production Config
+
+To run against production services (not recommended locally):
+1. Edit `.env` with production URLs
+2. Set credentials appropriately
+3. Ensure network access to production services
+
+---
+
+See `.env.example` for all available environment variables.

k8s/app/CONFIG.md

@@ -0,0 +1,157 @@
+# Poimen Memory - Environment Configuration Guide
+
+All downstream service URIs are read from environment variables, sourced from ConfigMap.
+
+## How It Works
+
+1. **ConfigMap provides URIs**: `k8s/app/config.yaml` (production, SOPS-encrypted)
+2. **Deployment injects via envFrom**: `envFrom: configMapRef: poimen-memory-config`
+3. **Application reads from ENV**: Code parses `LLM_ENDPOINT`, `OPENSEARCH_HOST`, `AUTHENTIK_ISSUER`, etc.
+
+```yaml
+# deployment.yaml
+envFrom:
+  - configMapRef:
+      name: poimen-memory-config  # All vars injected as ENV
+```
+
+## Environment Variables
+
+### LLM Service (Entity & Fact Extraction)
+- `LLM_ENDPOINT` — full URL to chat/completions endpoint
+- `LLM_API_BASE` — base API URL (used for client initialization)
+- `LLM_MODEL` — model identifier (ornith:35b, qwen:7b, etc.)
+- `LLM_TIMEOUT_SECS` — timeout for LLM requests
+- `ENABLE_LLM_EXTRACTION` — enable/disable LLM extraction (true/false)
+
+### OpenSearch (Vector Store, BM25)
+- `OPENSEARCH_HOST` — hostname:port
+- `OPENSEARCH_SCHEME` — http or https
+- `OPENSEARCH_VERIFY_CERTS` — SSL certificate verification (true/false)
+
+### Authentik (OIDC)
+- `AUTHENTIK_ISSUER` — OIDC issuer URL
+- `AUTHENTIK_VERIFY_SSL` — SSL certificate verification (true/false)
+- `MEM_AUTH_MODE` — auth mode: jwt | apikey | none
+
+### Temporal (Workflow Orchestration - Future)
+- `TEMPORAL_ENDPOINT` — temporal frontend hostname:port
+- `TEMPORAL_NAMESPACE` — temporal namespace
+
+### API Gateway (Route Optimization - Future)
+- `GATEWAY_URL` — gateway base URL
+
+### Memory Service Config
+- `MEM_AUTH_MODE` — jwt | apikey | none
+- `MEM_RATE_LIMIT_INGEST` — ingest requests per second
+- `MEM_RATE_LIMIT_QUERY` — query requests per second
+- `MEM_EMBEDDING_BATCH_SIZE` — batch size for embeddings
+
+---
+
+## Deployment Scenarios
+
+### Production (SOPS-Encrypted ConfigMap)
+
+**File**: `k8s/app/config.yaml`
+
+Services use cluster-internal DNS:
+```yaml
+LLM_ENDPOINT: http://reasoning-predictor.llm-serving.svc.cluster.local:8000/v1/chat/completions
+OPENSEARCH_HOST: opensearch.poimen.svc.cluster.local:9200
+AUTHENTIK_ISSUER: https://authentik.auth.svc.cluster.local:9443/application/o/poimen/
+TEMPORAL_ENDPOINT: temporal-frontend.temporal.svc.cluster.local:7233
+GATEWAY_URL: http://api-gw.poimen.svc.cluster.local:8080
+MEM_AUTH_MODE: jwt
+```
+
+**Deploy**:
+```bash
+# SOPS auto-decrypts based on .sops.yaml age key
+kubectl apply -f k8s/app/config.yaml -k k8s/app/
+```
+
+### Local/Development (Plaintext ConfigMap)
+
+**File**: `k8s/app/config.local.yaml`
+
+Services via external URLs (ingress):
+```yaml
+LLM_ENDPOINT: https://api.riotpiao.com/v1/chat/completions
+OPENSEARCH_HOST: opensearch.riotpiao.com:443
+AUTHENTIK_ISSUER: https://authentik.riotpiao.com/application/o/poimen/
+TEMPORAL_ENDPOINT: temporal.riotpiao.com:443
+GATEWAY_URL: https://api.riotpiao.com
+MEM_AUTH_MODE: none
+```
+
+**Deploy** (override production config):
+```bash
+# Delete prod config, apply local
+kubectl delete configmap poimen-memory-config -n poimen
+kubectl apply -f k8s/app/config.local.yaml
+```
+
+---
+
+## Encrypting with SOPS
+
+Production `config.yaml` is encrypted with SOPS (Age-based).
+
+**Encrypt**:
+```bash
+sops -e k8s/app/config.yaml > k8s/app/config.yaml.enc
+mv k8s/app/config.yaml.enc k8s/app/config.yaml
+```
+
+**Decrypt for editing** (SOPS auto-handles with $EDITOR):
+```bash
+sops k8s/app/config.yaml
+```
+
+**View decrypted** (without editing):
+```bash
+sops -d k8s/app/config.yaml
+```
+
+**.sops.yaml** defines encryption key:
+```yaml
+creation_rules:
+  - path_regex: k8s/app/config.yaml
+    key_groups:
+      - age:
+          - <age-public-key>
+```
+
+---
+
+## Application Code Pattern
+
+Example: Application should read URIs from ENV at startup.
+
+```rust
+// Pseudocode
+let llm_endpoint = env::var("LLM_ENDPOINT")
+    .unwrap_or("http://localhost:11434/v1/chat/completions".to_string());
+let opensearch_host = env::var("OPENSEARCH_HOST")
+    .unwrap_or("localhost:9200".to_string());
+let auth_mode = env::var("MEM_AUTH_MODE")
+    .unwrap_or("none".to_string());
+
+// Initialize clients with these URIs
+let llm_client = LlmClient::new(llm_endpoint)?;
+let search_client = OpenSearchClient::new(opensearch_host)?;
+```
+
+---
+
+## Summary
+
+| Aspect | Production | Local |
+|--------|-----------|-------|
+| **Config File** | `config.yaml` | `config.local.yaml` |
+| **Encryption** | SOPS (Age) | Plaintext |
+| **Service URIs** | Cluster-internal DNS | External HTTPS |
+| **Auth Mode** | JWT (Authentik) | None (disabled) |
+| **Rate Limits** | 100/1000 | 1000/10000 |
+| **Deploy** | `kubectl apply -k k8s/app/` | `kubectl apply -f config.local.yaml` |

k8s/app/config.local.yaml

@@ -0,0 +1,47 @@
+# Local/Development configuration (plaintext, external URLs via ingress)
+# Use this instead of config.yaml for local testing
+# kubectl apply -f config.local.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: poimen-memory-config
+  namespace: poimen
+  labels:
+    app.kubernetes.io/name: poimen-memory
+    app.kubernetes.io/component: config
+data:
+  # Auth mode: jwt | apikey | none (disabled for local testing)
+  MEM_AUTH_MODE: "none"
+  
+  # Rate limiting (higher for testing)
+  MEM_RATE_LIMIT_INGEST: "1000"
+  MEM_RATE_LIMIT_QUERY: "10000"
+  MEM_IDEMPOTENCY_TTL_SECS: "86400"
+  
+  # Embeddings
+  MEM_EMBEDDING_BATCH_SIZE: "32"
+  
+  # Downstream services - external URLs via ingress
+  
+  # LLM Service (via api.riotpiao.com ingress)
+  LLM_ENDPOINT: "https://api.riotpiao.com/v1/chat/completions"
+  LLM_API_BASE: "https://api.riotpiao.com/v1"
+  LLM_MODEL: "qwen:7b"
+  LLM_TIMEOUT_SECS: "60"
+  ENABLE_LLM_EXTRACTION: "true"
+  
+  # OpenSearch (via ingress)
+  OPENSEARCH_HOST: "opensearch.riotpiao.com:443"
+  OPENSEARCH_SCHEME: "https"
+  OPENSEARCH_VERIFY_CERTS: "true"
+  
+  # Authentik (via ingress - optional for local)
+  AUTHENTIK_ISSUER: "https://authentik.riotpiao.com/application/o/poimen/"
+  AUTHENTIK_VERIFY_SSL: "true"
+  
+  # Temporal (via ingress)
+  TEMPORAL_ENDPOINT: "temporal.riotpiao.com:443"
+  TEMPORAL_NAMESPACE: "poimen"
+  
+  # API Gateway (via ingress)
+  GATEWAY_URL: "https://api.riotpiao.com"

k8s/app/config.yaml

@@ -1,5 +1,7 @@
-# Non-sensitive environment variables for poimen-memory
+# Production environment configuration for poimen-memory
-# Change these without redeploying secrets.
+# All services use cluster-internal DNS names
+# This file is encrypted with SOPS in production
+# For local dev, use plaintext version with external URLs
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -9,19 +11,39 @@ metadata:
     app.kubernetes.io/name: poimen-memory
     app.kubernetes.io/component: config
 data:
-  # Auth mode: jwt | apikey
+  # Auth mode: jwt | apikey | none
-  MEM_AUTH_MODE: "none"
+  MEM_AUTH_MODE: "jwt"
+  
   # Rate limiting
   MEM_RATE_LIMIT_INGEST: "100"
   MEM_RATE_LIMIT_QUERY: "1000"
   MEM_IDEMPOTENCY_TTL_SECS: "86400"
+  
   # Embeddings
   MEM_EMBEDDING_BATCH_SIZE: "32"
-  # OpenSearch
+  
-  OPENSEARCH_HOST: "opensearch.poimen.svc.cluster.local:9200"
+  # Downstream services - read by application from ENV
-  # Obsidian
+  # Internal cluster DNS (prod) / external URLs (local)
-  # LLM Configuration (for entity extraction)
+  
-  LLM_ENDPOINT: "http://api-internal.riotpiao.com:8000/v1/chat/completions"
+  # LLM Service (entity extraction, fact extraction)
-  LLM_MODEL: "qwen:7b"
+  LLM_ENDPOINT: "http://reasoning-predictor.llm-serving.svc.cluster.local:8000/v1/chat/completions"
+  LLM_API_BASE: "http://reasoning-predictor.llm-serving.svc.cluster.local:8000/v1"
+  LLM_MODEL: "ornith:35b"
   LLM_TIMEOUT_SECS: "30"
   ENABLE_LLM_EXTRACTION: "true"
+  
+  # OpenSearch (vector store, BM25 retrieval)
+  OPENSEARCH_HOST: "opensearch.poimen.svc.cluster.local:9200"
+  OPENSEARCH_SCHEME: "http"
+  OPENSEARCH_VERIFY_CERTS: "false"
+  
+  # Authentik (OIDC provider)
+  AUTHENTIK_ISSUER: "https://authentik.auth.svc.cluster.local:9443/application/o/poimen/"
+  AUTHENTIK_VERIFY_SSL: "false"
+  
+  # Temporal (workflow orchestration - future)
+  TEMPORAL_ENDPOINT: "temporal-frontend.temporal.svc.cluster.local:7233"
+  TEMPORAL_NAMESPACE: "poimen"
+  
+  # API Gateway (external queue, route optimization - future)
+  GATEWAY_URL: "http://api-gw.poimen.svc.cluster.local:8080"

k8s/app/deployment.yaml

@@ -61,20 +61,12 @@ spec:
             - name: DATABASE_URL
               value: "postgresql://$(DATABASE_USER):$(DATABASE_PASSWORD)@$(DATABASE_HOST):$(DATABASE_PORT)/$(DATABASE_NAME)?sslmode=disable"
 
-            # LLM via api.riotpiao.com (Authentik JWT auth)
+            # All downstream service URIs read from ConfigMap
-            - name: LLM_ENDPOINT
+            # (LLM_ENDPOINT, LLM_API_BASE, LLM_MODEL, OPENSEARCH_HOST, etc.)
-              value: "https://api.riotpiao.com/v1/chat/completions"
+            # These are injected via envFrom below
-            - name: LLM_API_BASE
+            
-              value: "https://api.riotpiao.com/v1"
-            - name: LLM_MODEL
-              value: "ornith:35b"
-
             # Authentik service account (memory-agent-oidc secret)
-            - name: AUTHENTIK_ISSUER
+            # Only needed if MEM_AUTH_MODE=jwt in ConfigMap
-              valueFrom:
-                secretKeyRef:
-                  name: memory-agent-oidc
-                  key: ISSUER
             - name: AUTHENTIK_CLIENT_ID
               valueFrom:
                 secretKeyRef:
@@ -102,6 +94,7 @@ spec:
             - name: MEM_HOME
               value: "/tmp"
           envFrom:
+            # ConfigMap with all service URIs (prod: encrypted, local: plaintext)
             - configMapRef:
                 name: poimen-memory-config
           command: ["/app/mem"]

k8s/app/kustomization.yaml

@@ -1,13 +1,11 @@
 apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 namespace: poimen
+
 resources:
-  # vault-pvc.yaml removed — memory service uses pgvector, not local storage
   - deployment.yaml
   - service.yaml
-  - config.yaml
+  - config.yaml        # Production config (SOPS-encrypted)
-  # obsidian.yaml retired — reference docs now via memory graph
+
-  # Legacy secret managed separately
-  # - secrets.yaml
 generators:
   - secret-generator.yaml