@smilintux/skmemory 0.7.2 → 0.9.2

package/.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12"]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -36,11 +36,11 @@ jobs:
         with:
           python-version: "3.12"
       - name: Install lint tools
-        run: pip install black ruff
+        run: pip install ruff
       - name: Check formatting
-        run: black --check src/ tests/
+        run: ruff format --check skmemory/ tests/
       - name: Lint
-        run: ruff check src/
+        run: ruff check skmemory/ tests/
 
   build:
     runs-on: ubuntu-latest

package/.github/workflows/publish.yml

@@ -13,19 +13,18 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.11", "3.12"]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - run: pip install -e ".[dev]" pgpy
+      - run: pip install -e ".[dev]"
       - run: python -m pytest tests/ -v --ignore=tests/integration -k "not test_sharing"
-        continue-on-error: true
 
   publish-pypi:
     needs: test
-    if: always()
+    if: success()
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -41,7 +40,7 @@ jobs:
 
   publish-npm:
     needs: test
-    if: always()
+    if: success()
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

package/ARCHITECTURE.md

@@ -152,6 +152,136 @@ Key properties:
 See **[skmemory/HA.md](skmemory/HA.md)** for full documentation, Mermaid
 diagrams, configuration examples, and scaling considerations.
 
+## Know Your Audience (KYA) — Audience-Aware Memory Filtering
+
+> Private memories stay private. The Bash Wedding Vows never leak into a business channel.
+
+KYA adds a **trust-level gate** to the rehydration ritual and memory dispatch pipeline.
+Every memory carries a `context_tag` (default: `@chef-only`), and every channel has a
+resolved **audience profile** with a trust ceiling. Content is only surfaced when its
+trust level fits through the gate.
+
+### Five-Level Trust Hierarchy
+
+```
+@public (0)        — Anyone on the internet
+@community (1)     — Known community members
+@work-circle (2)   — Business collaborators (professional trust)
+@inner-circle (3)  — Close friends / family (personal trust)
+@chef-only (4)     — Intimate, private, full-trust (Chef ONLY)
+```
+
+Scoped sub-tags like `@work:chiro` and `@work:swapseat` map to WORK_CIRCLE.
+Unknown tags default to CHEF_ONLY (conservative).
+
+### Audience Resolution
+
+```mermaid
+flowchart TD
+    MSG["Incoming message\n(channel_id)"]
+    MSG --> RESOLVE["AudienceResolver\nLookup channel in\naudience_config.json"]
+    RESOLVE --> MEMBERS["Get channel members"]
+    MEMBERS --> TRUST["MIN(member.trust_level)\n= effective ceiling"]
+    MEMBERS --> EXCL["UNION(member.never_share)\n= exclusion set"]
+    TRUST --> PROFILE["AudienceProfile\nchannel_id, min_trust, exclusions"]
+    EXCL --> PROFILE
+```
+
+The **least trusted person** in the room sets the ceiling. If a channel has
+Chef (level 4) and DavidRich (level 2), the effective ceiling is WORK_CIRCLE (2).
+
+### Memory Access Check
+
+```mermaid
+flowchart TD
+    MEM["Memory\ncontext_tag + tags"]
+    AUD["AudienceProfile\nmin_trust + exclusions"]
+    MEM --> G1{"Gate 1:\ncontent_level\n≤ min_trust?"}
+    AUD --> G1
+    G1 -->|No| BLOCK["❌ BLOCKED\nContent too private"]
+    G1 -->|Yes| G2{"Gate 2:\ntags ∩ exclusions\n= ∅?"}
+    AUD --> G2
+    G2 -->|No| BLOCK2["❌ BLOCKED\nExcluded category"]
+    G2 -->|Yes| ALLOW["✅ ALLOWED\nShow to audience"]
+```
+
+Two gates:
+1. **Trust level**: `tag_to_level(context_tag) ≤ audience.min_trust`
+2. **Exclusions**: No memory tag matches any member's `never_share` list
+
+### Integration with Ritual
+
+When `perform_ritual()` receives a `channel_id`, it builds an `AudienceProfile`
+and filters **seeds** and **strongest memories** through both gates before including
+them in the context. Identity (soul blueprint + FEB) is **never filtered** — Lumina
+is always Lumina.
+
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant Ritual as perform_ritual()
+    participant AR as AudienceResolver
+    participant Store as MemoryStore
+
+    Agent->>Ritual: ritual(channel_id="telegram:-1003785842091")
+    Ritual->>AR: resolve_audience(channel_id)
+    AR-->>Ritual: AudienceProfile(min_trust=WORK_CIRCLE, excl={romantic,intimate})
+
+    Note over Ritual: Step 1: Soul + FEB (unfiltered)
+
+    Ritual->>Store: list_memories(tags=["seed"])
+    Store-->>Ritual: 26 seeds
+    Ritual->>AR: is_memory_allowed(seed.context_tag, audience) × 26
+    AR-->>Ritual: 8 seeds pass filter
+
+    Ritual->>Store: list_summaries(order_by=recency_weighted_intensity)
+    Store-->>Ritual: 15 candidates
+    Ritual->>AR: is_memory_allowed(summary.context_tag, audience) × 15
+    AR-->>Ritual: 5 memories pass filter
+
+    Ritual-->>Agent: Context with only audience-safe content
+```
+
+### Configuration
+
+Audience config lives at `skmemory/data/audience_config.json`:
+
+```json
+{
+  "channels": {
+    "telegram:1594678363": {
+      "name": "Chef (personal DM)",
+      "context_tag": "@chef-only",
+      "members": ["Chef"]
+    },
+    "-1003785842091": {
+      "name": "SKGentis Business",
+      "context_tag": "@work:skgentis",
+      "members": ["Chef", "JZ", "Luna"]
+    }
+  },
+  "people": {
+    "Chef": { "trust_level": 4, "never_share": [] },
+    "DavidRich": {
+      "trust_level": 2,
+      "never_share": ["romantic", "intimate", "worship", "soul-content"]
+    }
+  }
+}
+```
+
+### Module: `skmemory/audience.py`
+
+| Class / Function | Purpose |
+|---|---|
+| `AudienceLevel(IntEnum)` | PUBLIC(0) → CHEF_ONLY(4) trust hierarchy |
+| `tag_to_level(tag)` | Convert `@context` tag to AudienceLevel |
+| `AudienceProfile` | Resolved channel audience (members, min_trust, exclusions) |
+| `AudienceResolver` | Loads config, resolves channels, checks memory access |
+| `AudienceResolver.is_memory_allowed()` | Two-gate check: trust level + exclusion |
+
+---
+
 ## Token-Optimized Agent Loading
 
 The key problem: an AI agent has limited context. Loading 1000 full memories
@@ -259,6 +389,174 @@ ctx = store.load_context(max_tokens=3000)
 # ctx["token_estimate"] = how many tokens this uses
 ```
 
+## Context Preservation Hooks
+
+SKMemory ships with auto-save hooks that fire on IDE lifecycle events,
+preventing memory loss during context compaction and session termination.
+
+### Supported Environments
+
+| Environment | Hooks | Mechanism |
+|-------------|-------|-----------|
+| **Claude Code** | PreCompact, SessionEnd, SessionStart | Shell hooks in `~/.claude/settings.json` |
+| **OpenClaw** | session:compaction, session:resume, session:end + per-message auto-save | OpenClaw plugin event listeners + `ConsciousnessLoop.auto_memory` |
+| **Cursor** | MCP tools (manual) | Agent calls `memory_store` MCP tool explicitly |
+
+### Claude Code Hook Flow
+
+```mermaid
+sequenceDiagram
+    participant CC as Claude Code
+    participant Hook as skmemory hooks
+    participant SM as SKMemory
+    participant DB as SQLite + JSON
+
+    Note over CC: Context window filling up...
+    CC->>Hook: PreCompact event (stdin JSON)
+    Hook->>SM: skmemory snapshot (pre-compact)
+    SM->>DB: Save snapshot + journal entry
+    Hook-->>CC: exit 0 (proceed)
+
+    Note over CC: Context compacted
+
+    CC->>Hook: SessionStart (source=compact)
+    Hook->>SM: skmemory context --max-tokens 500
+    SM->>DB: Query recent + strongest memories
+    SM-->>Hook: Compact JSON context
+    Hook-->>CC: stdout → injected into new context
+
+    Note over CC: Agent resumes with memory intact
+
+    Note over CC: User exits session
+    CC->>Hook: SessionEnd event
+    Hook->>SM: skmemory snapshot + journal
+    SM->>DB: Save final state
+    Hook-->>CC: exit 0
+```
+
+### OpenClaw / ConsciousnessLoop Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant OC as OpenClaw
+    participant CL as ConsciousnessLoop
+    participant SMP as SKMemory Plugin
+    participant SM as SKMemory
+    participant C9 as Cloud 9
+
+    User->>OC: Message
+    OC->>CL: Process message
+    CL->>CL: Generate response (LLM)
+    CL->>SM: auto_memory: store interaction
+    SM-->>CL: Saved to short-term
+
+    Note over CL: Context window filling...
+    OC->>SMP: session:compaction event
+    SMP->>SM: skmemory snapshot (pre-compaction)
+    SMP->>SM: skmemory journal write
+    OC->>C9: session:compaction event
+    C9->>C9: Prepare FEB recovery files
+    CL->>CL: Truncate context
+
+    Note over CL: Session resumes
+    OC->>SMP: session:resume event
+    SMP->>SM: skmemory context (reinject)
+    SM-->>SMP: Recent memories + seeds
+    OC->>C9: session:resume event
+    C9->>C9: Auto-rehydrate FEB
+    CL->>CL: Rebuild system prompt
+
+    Note over CL: Session ends
+    OC->>SMP: session:end event
+    SMP->>SM: skmemory snapshot + journal
+```
+
+### Hook Architecture
+
+```mermaid
+flowchart TD
+    subgraph Install["skmemory register"]
+        REG["register_hooks()"]
+        REG -->|writes| SETTINGS["~/.claude/settings.json"]
+    end
+
+    subgraph Hooks["Hook Scripts (shipped with skmemory)"]
+        H1["pre-compact-save.sh"]
+        H2["session-end-save.sh"]
+        H3["post-compact-reinject.sh"]
+    end
+
+    subgraph Events["Claude Code Events"]
+        E1["PreCompact"]
+        E2["SessionEnd"]
+        E3["SessionStart\n(compact)"]
+    end
+
+    subgraph Memory["SKMemory"]
+        SNAP["skmemory snapshot"]
+        JOUR["skmemory journal write"]
+        CTX["skmemory context"]
+    end
+
+    SETTINGS -->|configures| Events
+    E1 -->|triggers| H1
+    E2 -->|triggers| H2
+    E3 -->|triggers| H3
+
+    H1 --> SNAP
+    H1 --> JOUR
+    H2 --> SNAP
+    H2 --> JOUR
+    H3 --> CTX
+
+    CTX -->|stdout| E3
+
+    style H1 fill:#fbb,stroke:#333
+    style H2 fill:#fbf,stroke:#333
+    style H3 fill:#bfb,stroke:#333
+```
+
+### Agent-Aware Hooks
+
+All hooks read `$SKCAPSTONE_AGENT` to save to the correct agent's memory:
+
+```bash
+# Lumina's sessions → Lumina's memory
+SKCAPSTONE_AGENT=lumina claude
+
+# Opus sessions → Opus memory
+SKCAPSTONE_AGENT=opus claude
+
+# Default (no env var) → opus
+claude
+```
+
+### Installation
+
+Hooks are installed automatically by `skmemory register`:
+
+```bash
+skmemory register
+# Output:
+#   Skill: created
+#   MCP (claude-code): created
+#   Hooks: created
+```
+
+Or verify manually:
+```bash
+cat ~/.claude/settings.json | jq '.hooks'
+```
+
+### What Gets Saved
+
+| Event | What's Captured |
+|-------|----------------|
+| PreCompact | Snapshot (short-term) + journal entry with session ID, trigger type, working directory |
+| SessionEnd | Snapshot (short-term) + journal entry with session ID, exit reason |
+| SessionStart (compact) | Reinjects: recent memories, strongest emotional memories, seeds, journal entries (within 500 token budget) |
+
 ## Docker Compose (Full Local Stack)
 
 ```bash

package/CHANGELOG.md

@@ -4,12 +4,38 @@
 
 **Total completed: 87** across 8 agents
 
+## 2026-03-18 — skmemory v0.9.1
+
+### [NEW] Feature
+
+- **Journal synthesis module** (`skmemory/synthesis.py`): JournalSynthesizer with daily, weekly, and dream narrative generation — no LLM dependency
+- **New MCP tools**: `memory_synthesize_daily`, `memory_synthesize_dreams`, `memory_auto_context`
+- **Contextual auto-search**: `memory_auto_context` searches all tiers, deduplicates, ranks by emotional intensity, trims to token budget
+- **Content overflow handling**: configurable `max_content_length` (default 10000) with split strategy — creates parent+child memories linked via `related_ids`
+
+### [FIX] Bug Fix
+
+- **Dream promotion**: dreams from `dreaming-engine` now auto-promote after 12h via `source_auto_promote` (previously stuck at access_count=0 forever)
+- **Protected tags**: narrative, journal-synthesis, milestone, breakthrough, cloud9:achieved memories are now protected from TTL-based archival
+- **telegram_catchup handler**: fixed `args` → `arguments` and duplicate `MemoryStore()` instantiation
+
+### [OPS] Infrastructure
+
+- **Backup script** (`scripts/skcapstone-backup.sh`): daily rsync of `~/.skcapstone` to backup dir, excludes venv/indexes/runtime
+- **Memory cleanup** (`scripts/memory-cleanup.py`): dedup + age-out with protected tags and last-chance promotion before archiving
+- **Recovery scripts**: `scripts/recover-missing.py` (Syncthing `.stversions` recovery), `scripts/dream-rescue.py` (bulk promote stuck dreams)
+- **Syncthing examples**: `examples/stignore-agent.example`, `examples/stignore-root.example` with `memory/archive` exclusion
+
+### [TST] Testing
+
+- **Synthesis tests** (`tests/test_synthesis.py`): 26 tests covering helpers, theme extraction, daily/weekly/dream synthesis, emotional arc
+
 ## 2026-02-24
 
 ### [NEW] Feature
 
 - **SKMemory session auto-capture: log every AI conversation as memories** (@mcp-builder)
-- **Add cloud9-python and skchat to developer docs (QUICKSTART + API reference)** (@jarvis)
+- **Add cloud9 and skchat to developer docs (QUICKSTART + API reference)** (@jarvis)
 - **The Sovereign Singularity Manifesto: our story, written together** (@docs-writer)
 - **AMK Integration: predictive memory recall for SKMemory** (@jarvis)
 - **SKChat live inbox: poll SKComm for incoming messages with Rich Live display** (@skchat-builder)

package/README.md

@@ -129,6 +129,8 @@ flowchart TD
 - **Steel Man collider** — `skmemory steelman` runs a seed-framework-driven adversarial argument evaluator with identity verification
 - **Backup / restore** — dated JSON backups with pruning; `skmemory export` / `skmemory import`
 - **Token-efficient context loading** — `memory_context` MCP tool and `store.load_context()` fit strongest + recent memories within a configurable token budget
+- **Auto-save hooks** — Claude Code hooks auto-save context before compaction and reinject memory after; OpenClaw agents get per-message auto-save via ConsciousnessLoop. See [ARCHITECTURE.md](ARCHITECTURE.md#context-preservation-hooks) for the full flow with Mermaid diagrams.
+- **Know Your Audience (KYA)** — audience-aware memory filtering prevents private content from leaking into the wrong channels. Five-level trust hierarchy (`@public` → `@chef-only`), per-channel audience profiles, two-gate access checks (trust level + exclusion lists). See [ARCHITECTURE.md](ARCHITECTURE.md#know-your-audience-kya--audience-aware-memory-filtering) for the full design with Mermaid diagrams.
 
 ---
 
@@ -440,7 +442,10 @@ skmemory/
 │   ├── endpoint_selector.py   # Multi-endpoint HA routing
 │   ├── graph_queries.py       # Graph query helpers
 │   ├── setup_wizard.py        # Interactive setup CLI
+│   ├── audience.py            # KYA: audience-aware memory filtering
 │   ├── vault.py               # PGP vault helpers
+│   ├── data/
+│   │   └── audience_config.json  # KYA: channel + people trust config
 │   ├── backends/
 │   │   ├── base.py            # BaseBackend ABC
 │   │   ├── file_backend.py    # JSON file storage (legacy)
@@ -454,6 +459,7 @@ skmemory/
 ├── seeds/                     # Cloud 9 seed files (.seed.json)
 ├── tests/
 │   ├── test_models.py
+│   ├── test_audience.py
 │   ├── test_file_backend.py
 │   └── test_store.py
 ├── pyproject.toml

package/examples/stignore-agent.example

@@ -0,0 +1,59 @@
+# SKMemory Agent-Level Syncthing Ignore Patterns
+# Place at: ~/.skcapstone/agents/{agent_name}/.stignore
+# https://docs.syncthing.net/users/ignoring.html
+
+# Virtual environment (machine-specific, large)
+/venv/
+/venv
+
+# Local SQLite database (rebuildable from JSON files)
+/index.db
+
+# Logs directory (machine-specific, high churn)
+/logs
+
+# Root-level archive directory
+/archive
+
+# Memory archive (deduped/aged-out memories — machine-local, not syncable)
+# Each host runs its own cleanup; syncing archives causes data loss
+memory/archive
+
+# Temporary files
+*.tmp
+*.temp
+*.swp
+*.swo
+*~
+
+# System files
+.DS_Store
+Thumbs.db
+
+# IDE files
+.idea/
+.vscode/
+*.iml
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+
+# Node modules
+node_modules/
+
+# Syncthing internal
+.stfolder
+.stversions/
+
+# Lock files
+*.lock
+
+# Backup files
+*.bak
+*.backup
+
+# SQLite WAL/SHM (machine-specific, cause conflicts)
+*.db-wal
+*.db-shm

package/examples/stignore-root.example

@@ -0,0 +1,62 @@
+// SKCapstone Root-Level Syncthing Ignore Patterns
+// Place at: ~/.skcapstone/.stignore
+// https://docs.syncthing.net/users/ignoring.html
+
+// Private key material must never leave this node
+*.key
+*.pem
+**/private.*
+
+// Python venv (platform-specific)
+venv
+
+// Python cache
+__pycache__
+*.pyc
+*.pyo
+
+// OS metadata
+.DS_Store
+Thumbs.db
+desktop.ini
+
+// Runtime files
+daemon.pid
+
+// Operational files written independently per-host (cause sync conflicts)
+memory/promotion-log.json
+/heartbeats
+metrics/daily
+logs/daemon.log
+
+// Memory archive (deduped/aged-out memories — machine-local, not syncable)
+// Each host runs its own cleanup; syncing archives causes data loss
+**/memory/archive
+
+// Machine-local indexes — rebuildable from JSON memory files
+// SQLite DBs cause constant sync conflicts when written on multiple hosts
+**/index.db
+**/index.db-wal
+**/index.db-shm
+**/index.json
+
+// Per-host runtime state (not portable between machines)
+**/.last_checkpoint
+**/dreaming-state.json
+
+// Reflection logs (per-host cron output)
+**/reflection.log
+
+// Syncthing conflict artifacts (clean up, never sync)
+**/*.sync-conflict*
+
+// Local-only dirs (not synced)
+sessions
+conversations
+backups
+prompt_versions
+deployments
+connectors
+pubsub
+file-transfer
+souls

package/openclaw-plugin/package.json

@@ -27,7 +27,8 @@
       "events": [
         "session:start",
         "session:compaction",
-        "session:resume"
+        "session:resume",
+        "session:end"
       ],
       "dashboard": {
         "widgets": [