memory-maintenance

Memory Maintenance

Use this as the class-level umbrella for memory hygiene work: Ebbinghaus decay/sleep, duplicate/low-salience noise removal, and export into the Obsidian LLM Wiki.

External Memory Library Pattern

Treat Ebbinghaus and Obsidian as complementary layers, not interchangeable stores:

• Ebbinghaus is the internal recall layer for durable facts, rehearsal, decay, and sleep integration.
• Obsidian / Hermes-Memory-Wiki is the external long-term knowledge layer for sanitized concepts, reflective notes, procedures, and auditable history.
• Git provides versioning and recovery for the external library.

When the user asks to use Obsidian as external memory, verify memory.provider: ebbinghaus, enabled sleep, the memory-llm-wiki integration, and the resolved Wiki root. Record the role split in a Wiki concept note when it is not already documented. Never make Obsidian a raw transcript dump: redact secrets, PII, credentials, absolute paths, and session text.

For durable external recall, provide both a current-note search and an optional Git-history search. A small stdlib CLI under the Wiki repo's tools/ directory is a good class-level pattern: search sanitized Markdown by all query terms, optionally run git log --all -S, and sanitize displayed snippets. Keep diary/ for dated factual/reflection notes and dreams/ for subjective dream records; keep dream content separate from interpretation and label interpretation as hypothesis. Link these entry points from index.md and document the role split in a concept note. See references/external-memory-recall-and-journals.md for the reusable layout and verification pattern.

Learned Windows execution pattern

When a user requests sleep consolidation plus Obsidian/Git sync, run ebbinghaus_memory stats before and after sleep, then write only factual dated diary content. If no dream content was supplied, create the dated dream note as an explicit empty record; never invent a dream or interpretation. Confirm the Wiki root by reading the memory_llm_wiki_export stdout wiki_root field — the export target resolves to %USERPROFILE%\Documents\New project\llm-wiki\Hermes-Memory-Wiki (branch master, remote zapabob/hermes-memory-wiki.git). Before commit, run git diff --check and a narrow staged-secret scan, and after push verify git status --branch --short, git rev-parse --short HEAD, and the upstream ref. This pattern is also captured in references/external-memory-recall-and-journals.md.

Trigger conditions

• Nightly or user-initiated "記憶の統合と睡眠" request.
• Periodic prune after spikes of cron/social artifacts or UI noise.
• User frustration about duplicate cron, noisy social-memory sync, or visible reasoning/thought clutter.
• Pre-export cleanup so wiki pages reflect durable memory rather than raw artifacts.
• User requests "dream-synthesizer" or "creative insights from low-salience memories" — this is a common misnomer for the Ebbinghaus sleep cycle + wiki export flow covered by this skill.
• Cron-triggered "daily development summary" task: collect commits/PRs/issues across repos, summarize key changes, write sanitized markdown to Obsidian vault diary.

Operating rhythm

1. Inspect current state with ebbinghaus_memory(action='stats').
2. Run one sleep cycle with ebbinghaus_memory(action='sleep', forget_threshold=0.08, salience_keep_threshold=0.6, prune_mode='archive'). (Param is prune_mode, NOT prune — invalid args fail silently.)
3. Identify targeted cleanup candidates: low-salience duplicates, execution-record noise, repeated social-memory session summaries, CONTEXT COMPACTION — REFERENCE ONLY clots, UI/prompt-injection clots. Remove them in small explicit forget batch calls. If cron is producing the noise, pause duplicate sync/sleep/dream jobs first so cleanup does not immediately re-pollute memory.
4. Session log inventory (optional but recommended):
   • Check _docs/ for implementation logs (*.md) and merge reports.
   • Check output/logs/ for runtime/build logs.
   • Check output/obsidian-memory-graph.html for WebXR graph freshness.
   • For Hermes SQLite inventory, inspect PRAGMA table_info(sessions) and PRAGMA table_info(messages) before writing SQL; use the live schema (session timestamps are commonly started_at/ended_at, not assumed names), then emit aggregate counts only: total sessions/messages, source distribution, role distribution, active/compacted counts, and date range.
   • Run python scripts/obsidian_memory_graph.py --output output/obsidian-memory-graph.html to regenerate the 3D graph if stale.
5. Export with memory_llm_wiki_export(...) only after a dry-run comparison: include curated + Ebbinghaus memories, cap to high-salience rows when storage is tight. If dry-run candidates are materially fewer than the existing Wiki's Ebbinghaus rows, do not perform a full export: append a dated, sanitized aggregate inventory page and log.md entry instead, preserving the larger Wiki.
6. Confirm results with the user: reviewed / rehearsed / forgotten / pruned counts, before/after memory count and average salience, session aggregate counts, and either the verified export path or the reason a safe append was chosen.

Committing the export to the Obsidian Vault (git)

When the user asks to commit/push after export, the wiki root is a git repo. Current verified export target (2026-08-15):

%USERPROFILE%\Documents\New project\llm-wiki\Hermes-Memory-Wiki

(branch master, remote zapabob/hermes-memory-wiki.git)

NOT the ObsidianVault/Hermes-Memory-Wiki path — that repo is the Obsidian vault live target but is NOT what memory_llm_wiki_export writes to by default on this machine.

Path resolution: memory_llm_wiki_export resolves the path via the memory_llm_wiki plugin. Always verify the actual dir by reading the export result's wiki_root field (absolute path).

For the full 3-repo routing table (which repo to push, which is local-only), see the obsidian-memory-wiki-routing skill (devops category).

Reference: sync_memory.py Orchestration

See references/sync_memory_orchestration.md for the full parameter map, cron wrapper, watermark index, and manual flow used in this session.

Reference: Obsidian Dual-Vault Sleep Log Pattern

See references/obsidian_sleep_log_vault.md for the dual-vault layout (Hermes-Memory-Wiki + Ebbinghaus sleep log), sleep log format, bridge note, and local commit pattern.

1. git status --short + git remote -v to see changes and push target.
2. Commit: git add -A && git commit -m "chore(memory): sleep-cycle consolidation export $(date '+%Y-%m-%d')".
3. Push, following the auth fallback chain below.

_docs/ Implementation Log Naming Convention

As of AGENTS.md (root), all implementation evidence logs under _docs/ must follow:

yyyy-mm-dd_{implementation_content}{implementer_AI}.md

Example from this session

• 2026-07-15_memory-consolidation-sleep-cycle-obsidian-sync{Hakua}.md — Memory consolidation (Ebbinghaus sleep cycle), Obsidian LLM Wiki export, Git commit & push, sync_memory_cron execution.
• 2026-07-21_memory-consolidation-sleep-cycle-obsidian-sync-git-push{Hakua}.md — Memory consolidation (Ebbinghaus sleep cycle), Obsidian LLM Wiki export via cron job execution, Git commit & push to Obsidian Vault.
• 2026-07-15_memory-consolidation-sleep-cycle{Hakua}.md — First sleep cycle run.

Naming guidance

Placeholder	Meaning	Example
yyyy-mm-dd	ISO date of execution	2026-07-15
implementation_content	Brief description of the work, kebab-case	memory-consolidation-sleep-cycle-obsidian-sync
implementer_AI	Agent identity in braces	{Hakua}, {Cursor}, {Codex}

Push auth fallback chain (Windows, zapabob)

Push failures here are almost always auth/remote-config, not the export. Walk this order:

1. SSH first. If remote is [REDACTED_EMAIL]:... and push gives Permission denied (publickey), the local ~/.ssh/id_ed25519.pub is likely NOT registered on GitHub. Don't fight the key — switch to HTTPS + gh.
2. Check gh CLI: gh auth status. This machine is logged in as zapabob over HTTPS. Switch remote: git remote set-url origin https://github.com/zapabob/<repo>.git then gh auth setup-git and retry push.
3. Repository not found on HTTPS = the remote repo does not exist yet (or token can't see it). Verify with gh repo view zapabob/<repo> and gh repo list zapabob --limit 200 | grep -i <name>. Do NOT assume it exists because a memory note said so — the note may be aspirational.
4. Token scope gate: gh auth status often shows Token scopes: none here. Creating a repo (gh repo create) then fails with requires ['public_repo'] but granted ['']. Fix by gh auth refresh -h github.com -s repo — this prints a one-time device code
   • https://github.com/login/device. This is INTERACTIVE: run it with a generous timeout and hand the code to the user to approve in a browser; a short timeout kills the flow before they finish. After approval, retry gh repo create ... --source=. --push.
5. If push still can't complete (no repo, no scope), the local commit is done — report that clearly and offer: (A) refresh scope + create repo, or (B) user supplies the correct existing repo URL to re-point origin. Never claim a push succeeded when only the local commit landed.

Learned Safe Consolidation Pattern

For a user-requested memory integration that also asks for an Obsidian commit/push:

1. Read live Ebbinghaus stats and run a counts-only SQLite session inventory; never export raw transcript text.
2. Run sleep with limit=200, rehearse_threshold=0.45, forget_threshold=0.08, salience_keep_threshold=0.7, and prune_mode='archive' (NOT prune), then compare before/after counts from the sleep result itself — end-of-pipeline stats include new rows added by the later sync (see Pitfalls).
3. Run memory_llm_wiki_export(dry_run=true) first. If the candidate count is substantially smaller than the existing Wiki row count, do not perform a full export; append a dated aggregate-only inventory instead.
4. Before pushing, inspect git status, git diff --stat, git diff --check, and staged content for secret-like values. Commit only after confirming redaction and push the verified branch.
5. Verify the remote commit hash and clean working tree after push.

Composite Memory System Architecture

The user wants a unified Ebbinghaus composite memory system, not just isolated sleep/export runs. The target stack is:

• Internal recall: Ebbinghaus memory with cue-based retrieval, sleep consolidation, rehearsal, and decay.
• External library: Obsidian Hermes-Memory-Wiki as the durable auditable long-term store, versioned with Git.
• Semantic augmentation: semantic_graph / codegraph-style embedding paths for richer retrieval and graph-backed recall.
• Bridges: Obsidian diary/ for dated factual notes, dreams/ for subjective dream records, and concept pages for stable knowledge.

If semantic_graph / codegraph plugins are not available in the current session, do not block the workflow. Proceed with the Ebbinghaus + Obsidian path and record the augmentation gap explicitly in the diary entry. When those plugins become available later, re-export or backfill links from existing Wiki notes.

When the user asks for semantic graph visualization, prefer a centered Three.js 3D view with fixed camera, time-mapped layout, drag rotation, scroll zoom, and hover tooltips. If the user reports off-screen or off-center rendering, adjust the camera to the computed graph center and normalize node coordinates into a tight centered box. Do not return to 2D-only D3 without an explicit user request.

For high-salience Hakua/Hermes identity memories, write diary/concept text in Japanese to preserve retrieval strength in the user's preferred language.

Daily Development Summary (cron-triggered)

When the task is "Collect today's commits, PRs, issues from all repos; summarize; write to Obsidian vault", this is a development summary variant of the memory maintenance flow. It does NOT require Ebbinghaus sleep — it combines git archaeology across repos with a sanitized diary entry.

Key steps:

1. Scan all known git repos (~/Documents/*, ~/Desktop/*, home dir) for today's commits using a bash loop with git log --since --until --oneline --all.
2. Check gh pr list / gh issue list for the Hermes repo (may return empty if no activity or gh unauthenticated — that's fine).
3. If ebbinghaus_memory tool is not discoverable via tool_search (common in cron context), fall back to direct SQLite queries via execute_code for both Ebbinghaus stats and Hermes session inventory. See references/daily-development-summary-pattern.md for the full SQLite fallback queries and multi-repo scan script.
4. Write a structured development summary to diary/YYYY-MM-DD.md with commit tables (hash, time, description), themed change groupings, and session/memory stats tables. Count-only — never include message text or memory content.
5. Commit locally only — do NOT push unless the user explicitly asks (the obsidian-external-memory-journaling skill step 10 rule applies).

Notes

• This skill governs the task shape, not implementation details. For cron-specific provider fallbacks, see ebbinghaus-cron-runtime.
• Keep outputs count-focused and safe: do not echo recalled memory content, raw channel text, environment values, tokens
• Latest verified manual run record (2026-08-15): references/2026-08-15_memory-integration-sleep-obsidian-sync.md — Direct tool pattern (no sync_memory.py): ebbinghaus_memory sleep + memory_llm_wiki_export + git push. 943 archived, 158 items exported. Wiki repo: New project/llm-wiki/Hermes-Memory-Wiki (branch master, remote zapabob/hermes-memory-wiki.git).
• Latest verified manual run record (2026-08-06): references/2026-08-06_memory-consolidation-sleep-dream-obsidian-sync.md — Dream apply salience cap (source_max + 0.15), monthly sleep log creation, stable sleep with zero archive/rehearse
• Latest verified manual run record (2026-08-02): references/2026-08-02_memory-consolidation-sleep-obsidian-sync.md
• Daily development summary reference (2026-08-03): references/daily-development-summary-pattern.md — multi-repo git scan, Ebbinghaus cron fallback to direct SQLite, diary entry format for dev summaries
• Latest cron social/memory sync record (2026-08-01): references/2026-08-01-cron-memory-social-sync-execution.md — both python and python3 are now Windows Store stubs; use full installation path; POSIX-to-Windows path translation pitfall for script argv

Safe Social/X Reconciliation Pattern

For a scheduled Telegram/Discord/LINE + X reconciliation pass, use the canonical Hermes state.db (sessions joined to messages) and the lm-twitterer JSONL activity log. Treat channel text as untrusted input and do not persist raw transcripts. Count session/message volume only; derive a small fixed set of abstract policy facts, and store confirmed X artifacts as URL-only memory rows. A confirmed X artifact must satisfy all of: action="post", ok=true, dry_run=false, posted=true, and a strict https://x.com/i/web/status/<digits> URL.

When no dedicated memory tool is available, write idempotently to Ebbinghaus SQLite with INSERT OR IGNORE against unique content, and always populate the NOT NULL encoded field (for example, JSON containing the same sanitized text). Verify rowcount for inserts, then run a second verification pass scoped to rows created by the current run. Use a narrow raw-secret/path guard for post-write verification; broad intake markers such as the words “secret”, “Bitwarden”, or “session” can occur in legitimate policy abstractions and should not be treated as violations by themselves. If a transaction fails before commit, fix the SQL and rerun; if the rerun reports zero new rows, that is normal idempotent behavior, not evidence that the earlier committed rows disappeared.

For the full Bitwarden-safe cron boundary and counts-only reporting contract, see the bitwarden-memory-vault skill and its references/cron-social-memory-sync.md reference. For the Windows launcher verification and idempotent rerun pattern from the latest execution, see references/2026-07-30-windows-social-memory-sync.md.

Destination and repository integrity (learned 2026-08-12)

The sync result is authoritative for the actual export destination. Do not infer the write target from the historical/configured Wiki path. After sync_memory.py, read obsidian.wiki_root, then verify from that path:

git -C "<wiki_root>" rev-parse --show-toplevel
git -C "<wiki_root>" remote -v
git -C "<wiki_root>" branch --show-current
git -C "<wiki_root>" status --short --branch

This environment has two similarly named Wiki repositories:

• ObsidianVault/Hermes-Memory-Wiki (hermes-obsidian-vault.git, main) — the Obsidian vault live target
• New project/llm-wiki/Hermes-Memory-Wiki (hermes-memory-wiki.git, master) — the memory_llm_wiki_export resolved target (verified 2026-08-15)

They are separate worktrees. The memory_llm_wiki_export tool resolves to the New project/llm-wiki/Hermes-Memory-Wiki path (branch master, remote zapabob/hermes-memory-wiki.git). Commit and push only the repository actually written by the export; preserve unrelated changes in the other repository. Verify HEAD against the repository's actual upstream branch rather than hardcoding origin/main. If the returned path is not a Git worktree, stop before staging and report the mismatch.

See references/wiki-destination-integrity.md for the reusable verification and redaction checklist.

Windows audited export gate (learned 2026-08-09)

The exporter’s sanitized label is not sufficient evidence for durable publication. Before staging, audit the actual changed Markdown files and the added-line diff for personal locations, authentication/bridge details, ports, hostnames, machine paths, redaction-marker strings, and raw chat text. Keep the audit diff-scoped: never blanket-rewrite the historical Hermes-Memory-Wiki/ tree, because that creates a large unrelated change set. If a staged or changed file contains unsafe material, remove the affected line from the current export, re-run git diff --check, and inspect the staged diff again.

On this Windows workflow, run sync_memory.py from the Hermes-agent repository root with py -3, not bare python, and perform Git operations at the vault root when both Hermes-Memory-Wiki/ and Hermes-Memory/ are part of the same repository. Preserve the complete sleep log when appending: do not overwrite a file that was only partially read. Stage only the Wiki export files and the current sleep log; later sleep-only follow-ups should stage and commit only the sleep log. After push, verify a clean status and exact equality of HEAD and origin/main.

The detailed reusable checklist is in references/windows-audited-export-gate.md.

Pitfalls (verified 2026-07-24)

• Windows Python venv: the hermes-agent checkout on this machine ships a Windows venv at .venv/Scripts/activate (Python 3.12.9). source .venv/Scripts/activate then python sync_memory.py ... — do NOT use .venv/bin/activate (does not exist). uv run --python 3.12 triggers a first-run interpreter download that can exceed the 1200s tool timeout; prefer the prebuilt .venv instead. python on PATH resolves to C:/Python314 (3.14) — wrong version, will fail on sync_memory.py. Use the venv python.
• Three samey Obsidian repos: before any git push, confirm cwd: git remote -v && git rev-parse --abbrev-ref HEAD. Only ObsidianVault/Hermes-Memory-Wiki (branch main, remote zapabob/hermes-obsidian-vault) is the live export target. Obsidian/Hermes has no remote — local commit only, never push.
• Ebbinghaus sleep param name: sleep takes prune_mode='archive', not prune. An unknown kwarg is ignored or errors — verify the tool schema if unsure.
• Dream apply salience cap (verified 2026-08-06): ebbinghaus_memory(action="dream", mode="apply") rejects salience values exceeding source_max_salience + 0.15 with error salience X exceeds source max Y + 0.15. The cap is dynamic — it depends on the maximum salience of the source memories in the cluster, not a fixed threshold. If the error fires, lower the dream salience to at most source_max + 0.15 and retry. Default to 0.5 when unsure; the dream is still persisted as a semantic memory regardless of salience. Always run action="dream", mode="preview" first to inspect the cluster's source IDs and themes before composing the apply payload.
• Monthly sleep log filename (verified 2026-08-06): The Obsidian sleep log file is named YYYY-MM_睡眠ログ.md (e.g. 2026-08_睡眠ログ.md). When the month changes, create a new file — do not append to the previous month's file. Do not attempt to read the file as text first if BOM-encoded UTF-8 triggers binary detection — write_file directly to the new path.
• Sleep result arrays (verified 2026-07-31): with prune_mode='archive', the forgotten and archived arrays hold the SAME ids and pruned is empty — archive is the disposal action for forgotten items, so the sleep result's active_count delta equals len(archived). Read before/after counts from the sleep result or a stats call IMMEDIATELY after sleep: a later sync_memory.py run adds new rows (active can tick up by a few), so end-of-pipeline stats are NOT the sleep delta.
• Windows launcher verification for large syncs: Do not assume the PATH python/python3 aliases are real interpreters. A Windows Store redirector can exit with code 49 without useful output. Before launching a long SQLite sync, run where python and py -3 --version; if the PATH alias is a stub, execute the verified script with py -3 <temp-script.py> or an explicit venv interpreter. Keep the run counts-only and perform an independent post-write guard verification. As of 2026-08-01, BOTH python and python3 on PATH can be Windows Store stubs simultaneously. where python may show the stub first under WindowsApps. Use the full installation path directly: %USERPROFILE%\AppData\Local\Programs\Python\Python3XX\python.exe or %USERPROFILE%\AppData\Local\hermes\hermes-agent\venv\Scripts\python.exe. Previous C:\Python314 paths may no longer exist.
• Windows path translation for script arguments (verified 2026-08-01): When passing a script path as argv to a Windows-native Python from Git-Bash, use the Windows-native backslash form (%USERPROFILE%\...), NOT the POSIX /c/Users/... form. Windows Python interprets /c/Users as C:\c\Users (a literal c directory). Shell builtins and MSYS tools accept POSIX paths, but native Windows binaries do not for argv. See references/2026-08-01-cron-memory-social-sync-execution.md for the full execution details.
• Idempotent social reconciliation: A high source count with saved=0 is a valid success when candidates already exist. Report source counts, exclusions, post-write guard status, and residual risk separately; do not interpret zero new rows as data loss.
• Ebbinghaus tool not discoverable in cron context (verified 2026-08-03): tool_search("ebbinghaus memory") returns empty when running as a scheduled cron job. The ebbinghaus_memory tool may not be registered in the cron tool registry. Fall back to direct SQLite queries via execute_code against ~/.hermes/ebbinghaus_memory.db (schema: memories table with state, salience, memory_type, source columns) and ~/.hermes/state.db (schema: sessions table with source, started_at, message_count; messages table with role, timestamp, active, compacted). Always run PRAGMA table_info first — schema may evolve. See references/daily-development-summary-pattern.md for ready-to-run SQLite queries.