
* VS Code hooks 
    https://docs.github.com/en/copilot/reference/hooks-configuration
    Session Start - output is ignored!
    User Prompt Submitted

* Codex hooks
    (haven't yet investigated)

* doc: make it really clear that `keep now foo` does NOT update the tags, the previous tags are still there

* need to make sure the tagging instructions are as clear as poss
    - reference `keep get .tag/act` directly

* can `keep config` return error status if there's no correct configuration yet?

* `keep reflect --something` that helps trigger "hourly reflection"?
    (different "reflect docs" would do that, but... do we want mmore than one?)

* lectio
    - encourage "deep reflection" on items that were important
      e.g. URLs and files that were captured recently

* let's explore some semantic relationships that are important
    the thing we're talking about is related to (many of):
    - a meeting or other event
    - people
    - places
    - events in the world
    do we want to go down the whole "entity extraction" thing? really?
    but we absolutely do need to handle "hey, note about XYZ, ...." whare XYZ is a capital-E Entity;
    or "I just talked to Z and T"
    maybe the entity-extraction is done by the AGENT, huh?
    - so the agent should tag "entities" in a consistent way, but it's just a convention, not rules
        -t class=Person entity=Daniel

* let's explore the macOS native entities (not just the filesystem things):
    - contacts
    - music (albums, artists, tracks, ...)
    - notes
    - health data
    (etc)...
    - want URLs for each of these so that we can represent them in our database with summaries and tags

* Some tools (e.g. VS Code) don't really have a global config.
  But if keep is running within a git project, in one of these tools,
  and there's no keep "hook" within the project itself, should we prompt to install it?

* USECASES.md "what is this great at"
    lesson zero: the context window doesn't really matter if you have exponentially-good navigation
        (tiny chunks loosely joined)

    lesson one: embeddings plus tagging plus summaries is a whole new thing, actually
        (especially for capturing knowledge about many document, links, references)

    so, the great use cases?
        - personal agent:
            - first, like a bookmark-manager with superpowers
            - or a research-assistant with superpowers
        - what else?

    And, how do we suggest the agents to /create higher structures/ as they work?
        - tags: locate your stuff by project, topic
        - update with all relevant documents as you research
        - update with all relevant URLs as you research
        - more tags?  update with descriptions-of-tags?  auto-summarize to make descriptions-of-tags?

* re-test the gemini path

* dynamically detect available models using the provider's API?
    - we could do this, but when?
    - no capability for "model migration and re-embedding" yet

* Measure some outcomes.  Describe behavior in openclaw, in claude code, etc.  Show where it works.

* tag-by-model ("auto-tag")?
    - is there a model-supported tagging? what would that need to be useful? (specific domains??)
      - i.e. as well as summarization, there's a "system document" that the model reads, and uses that document to decide which tags should be applied
      - it really needs to be one document per tag (because the model might choose multiple tags)
      - these are "system documents"
    - want this to be pluggable, guide the model-driven tagging from a sysdoc that defines how it works
    - want "references" for this too... maybe later

* check - what is your emotional response when encountering this project the first time?

* check for compatibility with linux (so far I've exclusively been running on macOS)
    can deploy on rpi at home
    also think about what would differ if we wanted to run this within docker, or in a k8s cluster

* check for compatibility with windows
    not sure we need to support powershell, only WSL? but paths etc. will vary
    and I don't know if windows has local models available through system services yet (would be nice)
    - this is all investigation work, not implementation  (I don't have a test environment)

* add support for the kimi/moonshot models, etc - what are we missing? compare claude code, openclaw

* add an audio track (mp3, flac, or something similar) to the library
    - keep it small tho, under a megabyte?
    - public domain recording of a song that resonates with the instructional content?
    - use as content but don't really want add dependencies on mp3/flace/wav decoding (especially anything requiring a license such as the fraunhofer stuff, all our deps must be MIT-compatible)
    - getting tags out of the file would be a great test case
    - analysis of the audio content will depend on the available models, but some might do a good job
    - whisper-cpp etc? outside our scope
      but I do want a semantic index of my music library

* add an image; same strategy as audio

* also support docx

* multi-embeddings
    - background task can detect current config and maintain compat

* review the CLI completely.  Can the common tasks have single-letter aliases for their commands?

* how do we get the claude-code model context?

* how do we get the vscode model context?  I really don't want to require a plugin too
    - can the agent just tell keep how to find the current providers??
    - that would be commandline, or per-session config, not per-repo or whatever (right???)

* can we do something similar for kiro?

* `keep save "thread-name"` — move now history into a named item, reset now
    - rename current `now` doc (with all version history) to a named item
    - useful for closing finished threads: "this conversation is done, archive it"
    - less clear for context switching (there-and-back-again) — tags on `now` may be better
    - implementation: rename across SQLite + ChromaDB (both document_store and vector store)
    - pointers: saved item gets a markdown link back to where it came from, now gets a link to saved item

* better update/degrade memory strategies: compare with current best of breed
    - want something that tracks last-retrieval time
    - not sure how that applies to the ranking for retrieval
    - do we need any of this to be config not code??
 
----

Done: (finished items go at the end)

. start a todo list for notes
. move the test docs into docs/library (the soul docs)
. move docs/README to docs/INDEX.md
. be clear that the tags are overlay, not replace
. lazy-load embedding/summarization providers for offline read-only operations
. fix __del__ crash when embedding provider fails to initialize
. karma (AN5.57): "I am the owner of my deeds and heir to my deeds".
. `keep -v` please, for debug-level logging to stderr
. CLI-first documentation ordering in REFERENCE.md and QUICKSTART.md
. enable "local config" - tree-walk config discovery, KEEP_CONFIG envvar, store.path config option
. tag docs: "one value per key" documented in REFERENCE.md
. tag-update CLI and tag() API for updating existing documents
. delete tags via empty string or --remove flag
. `keep tag KEY` works with key only (any value)
. `keep tag --list` and `keep tag KEY --list`
. rename source_tags → tags (with deprecation warning)
. KEEP_TAG_* environment variables for auto-tagging
. [tags] config section for default tags
. summaries: --summary flag, smart remember (short content verbatim), max_summary_length config
. documentstore already correct (stores only summaries, not full content)
. remember vs update: keep separate (different input semantics, both useful)
. model dimensions: lazy detection for unknown models (OpenAI, Gemini)
. `keep init` works offline - providers lazy-loaded, no network at init
. `process-pending` robust to offline - retries with max 5 attempts, graceful degradation
. startup cost optimized - read-only commands don't load providers
. error handling: log tracebacks to /tmp/keep-errors.log, show clean message to user
. timestamps always UTC - verified all datetime.now uses timezone.utc
. --since option for time-based filtering: accepts ISO duration (P3D, P1W, PT1H) or date (2026-01-15)
. time-based filtering on find, similar, search, tag commands
. system tags documented in docs/SYSTEM-TAGS.md (implemented vs reserved, protection mechanism)
. `keep` with no args shows current working context (the "now")
. `keep now` command to get/set current context
. get_now() and set_now() API methods with auto-create on first access
. default "now" content in docs/system/now.md (pre-loaded content pattern)
. unified output format: ID [tag1=val1, tag2=val2, ...] with all tags shown
. renamed 'builtin' to 'system' (docs/builtin → docs/system, _load_builtin → _load_system)
. `keep tag xyz` lists VALUES for key (not documents)
. `keep tag xyz=foo` lists DOCUMENTS with that tag
. what is the "warning" for HF sentence trqansformers
. preload system docs (conversations.md, domains.md) with special IDs (_system:*) and tags from frontmatter
. fixed CLI help consistency: `keep now` examples now match option descriptions
. document versioning: retain history on update, same id with version counter
    - PRAGMA user_version for schema migrations, document_versions table
    - address by id (newest) or id+offset (0=current, 1=previous)
    - prev/next navigation in frontmatter output
    - `keep get -V N` and `keep now -V N` for specific versions
    - `keep get --history` and `keep now --history` to list versions
    - text-mode updates use content-addressed IDs (_text:{hash}) for versioning
    - ChromaDB stores versioned embeddings as {id}@v{N}
. composable history: `keep list` IDs-first, `--ids --history` outputs @V{N} identifiers
. typer version compat: uv/venv recommended in docs, removed ImportError guards for core deps
. `keep now --history` and `keep get _now:default --history` produce identical output
. condensed tags in frontmatter: YAML flow format `{key: value, ...}`
. similar items in frontmatter: max 3, version-aware filtering, `--similar`/`--no-similar` flags, `-n` limit
. disable Rich markup in CLI help (plain text, teletype-safe)
. Ancrene Riwle attribution: James Morton, Camden Society 1853
. AN5.57 URLs added to INDEX.md
. consolidated three output formats: --ids (versioned ID), --full (YAML frontmatter), default (summary line)
. self-healing install: Layer 0 in SKILL.md teaches agents to install Protocol Block in system rules
x `context` text alongside summaries? (no, summary is good now)
. review how system documents (e.g. "metaschema") are used today, if any
. consolidated `keep tag` into `keep list`: --tag for filtering, --tags for listing, --since for time filtering
. changed "context" to "intentions" in `keep now` docs and docstrings
. `keep --version` flag to show version and exit
. `_system:library` document with URI templates for library files
. tag filtering for find, get, now: -t filters results/versions (context-dependent with set behavior)
. document project/topic segregation: SKILL.md, README.md, REFERENCE.md, AGENT-GUIDE.md; KEEP_COLLECTION envvar
. reviewed library content and docs for alignment with teachings (AN5.57, impermanence verse, forty-two chapters all support the practice)
. restructured SKILL.md Layers 1 & 2: integrated Language-Action (ground) + MN61 (mirror) teachings without duplication
. enhanced `keep config`: get any setting from CLI, added file/tool paths, test with `ls $(keep config tool)`
. HTML content regularization: HttpDocumentProvider extracts text from HTML at fetch time (matching FileDocumentProvider), fixing web URL summarization
. tag-based filtering: -t flag on list/find/get/similar filters by tag; --tags lists distinct tag values; --since for time filtering
. contextual summarization: user tags provide context for LLM summaries; _gather_context finds similar items with matching tags (OR-union, score boosted per tag match); tag changes trigger re-summarization
. remove `keep init`, streamline API and key selection, and add VoyageAI support for embeddings
. check functionality using Claude Desktop
. binary embedding cache: struct.pack float32 replaces json.dumps (~3.3x smaller), transparent migration, migrate() for bulk conversion
. fix summarizer contamination: removed product-name example from system prompt, context passes topic keywords not raw summaries, boundary instruction in contextual prompt
. terminal-width-aware summary lines: shutil.get_terminal_size with 120-col default for agents, real terminal width for humans
. add `keep delete`
. add `keep reflect` command with reflection instructions
. better plugin-hooks for claude code
. better readme: BLUF "what this is and why" replaces "what it does" tagline
. auto-install integrations: keep/integrations.py with TOOL_CONFIGS pattern, Claude Code hooks auto-installed on first run
. now.md onboarding: default nowdoc guides agents to read SKILL.md and foundational teachings (SYSTEM_DOCS_VERSION 4)
. TTY-gated reflect prompt: "As an agent, you should reflect" only shown when stdout is not a TTY
. shell-safe ID quoting: _shell_quote_id() wraps IDs with special chars in single quotes (text output only, not JSON)
. last-accessed rank bump: accessed_at column, touch/touch_many, --sort accessed on list, schema v2 migration
. codebase cleanup: removed dead modules (indexing.py, chunking.py, context.py), dead code (_timestamp, AVAILABLE_SETTINGS, enable_verbose_mode), fixed mock signatures, consolidated tag parsing, unified tag-update output
. rename for compact usage: `keep update` → `keep put`, `keep delete` → `keep del` (old names kept as hidden aliases)
. speech-act tagging: `act` tag (commitment, request, offer, assertion, assessment, declaration) and `status` tag (open, fulfilled, declined, withdrawn, renegotiated) with system docs (_tag:act, _tag:status, _tag:project, _tag:topic), woven into conversations.md, domains.md, SKILL.md, AGENT-GUIDE.md, REFERENCE.md, reflect.md
. tag description system docs: _tag:* IDs with `context: tag-description` frontmatter, loaded via SYSTEM_DOC_IDS registry (SYSTEM_DOCS_VERSION 5)
. reflect.md updated with act/status tag examples for commitment tracking
. _accessed and _accessed_date system tags: exposed accessed_at from DocumentStore as queryable tags, added item.accessed property, documented in SYSTEM-TAGS.md
. surface similar items on create/update: `keep put` and `keep now` show similar items in output as occasions for reflection
. anthropic OAuth token support: CLAUDE_CODE_OAUTH_TOKEN as alternative to ANTHROPIC_API_KEY, documented distinction between API keys (sk-ant-api03-...) and OAuth tokens (sk-ant-oat01-...) from `claude setup-token`
. document indexing practice: added guidance to SKILL.md, reflect.md, and Protocol Block instructing agents to index important documents (URLs, files) encountered during work with appropriate tags explaining what and why
. timestamps: seconds-precision UTC, no timezone suffix in frontmatter (stored and displayed)
. ID prefix rename: _text:hash → %hash, _system:foo → .foo, _tag:foo → .tag/foo, _now:default → now. Migration renames old IDs, SYSTEM_DOCS_VERSION 6, % added to shell-safe pattern.
. aligned ID column in `keep list` output (capped at 20 chars)
. QUICKSTART.md reordered: keep[local] shown before API key options
. Ollama support: auto-detection via /api/tags (0.5s timeout), smart model selection (embed vs generative), OLLAMA_HOST env var, priority between API keys and MLX
. `keep put --suggest-tags`: shows tag suggestions from similar items with frequency counts
. `keep add` as hidden alias for `keep put` (alongside existing `update` alias)
. openclaw AGENTS.md detection: install protocol block into AGENTS.md in cwd (openclaw sets cwd to workspace)
. `keep get` accepts multiple IDs: `keep --ids list -n 5 | xargs keep get` works; items separated by `---`
. `keep del` accepts multiple IDs
. inline content safety: --summary rejected for inline/stdin, length limit enforced, default max_summary_length bumped 500→2000
. meta-docs: .meta/* system docs with tag-based contextual resolution; todo/learnings/decisions surface in `now` and `get` frontmatter (SYSTEM_DOCS_VERSION 7)
. aligned ID column in frontmatter sections (similar, meta, prev/next) — same strategy as `keep list`, capped at 20 chars
. meta section namespace: `meta/todo:` prefix in frontmatter output prevents conflicts with built-in keys (prev, next, similar)
. openclaw plugin rework
. "remember X when Z" - covered by meta-docs
. compact bundled_hash: truncated _content_hash to 10 hex chars, migration for existing data
. `keep get --meta`: dedicated meta mode with -n limit, removed --no-similar
. decision: no edges in the data model, at least for a while.  The meta tags are dynamic edges.
. readme note Shinn et al. "Reflexion" (very cool, and a lot earlier)
. add persistence instructions for Kiro
. small extension to bootstrap instructions
. `keep now -f` removed (not useful)
. hooks rework (claude code, openclaw, add kiro)
. skills/docs rework
