ideadump 0.0.2__tar.gz

ideadump-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

ideadump-0.0.2/.gitignore

@@ -0,0 +1,119 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

ideadump-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thorwhalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ideadump-0.0.2/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: ideadump
+Version: 0.0.2
+Summary: A place to dump ideas: capture them in your own words, research them a little, index and relate them, and find them again
+Project-URL: Homepage, https://github.com/thorwhalen/ideadump
+Project-URL: Repository, https://github.com/thorwhalen/ideadump
+Project-URL: Documentation, https://thorwhalen.github.io/ideadump
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skills,claude-code,dol,ideas,knowledge-management,notes,research
+Requires-Python: >=3.10
+Requires-Dist: cw<0.2,>=0.1.1
+Requires-Dist: dol
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: git
+Requires-Dist: acquaint>=0.0.18; extra == 'git'
+Description-Content-Type: text/markdown
+
+# ideadump
+
+A place to dump ideas: capture them in your own words, research them a little, index and relate them, and find them again.
+
+```bash
+pip install ideadump
+```
+
+You tell an agent an idea in passing; it runs one command to keep it, verbatim, and a light research pass to see what it is called, what already exists and whether it is promising. Later you ask what ideas you have about something, or whether anything you have been working on relates to them.
+
+```bash
+ideadump add "a place to dump ideas, and do a bit of research on them" --title "Idea dump" --tags "tools, notes" --source my-session
+ideadump note idea-dump --file light-research.md --depth light     # attach research notes
+ideadump find "note taking research"                                # ranked, with the shared words
+ideadump find --file recent-work.md                                 # which ideas relate to this page of recent work?
+ideadump ls --status promising
+ideadump show idea-dump
+```
+
+Research is done by the agent with whatever search tools it has, so it sends queries (generic terms, not your notes) to outside services; the ideas themselves stay in your store.
+
+The primary user is an agent: the package ships a skill, `ideadump`, that tells it when and how to use these verbs (capture, light and deep research, linking, the "is my recent work related to my ideas" pass). See [Agent skill](#agent-skill).
+
+## Where ideas live
+
+Ideas are kept in a [dol](https://github.com/i2mint/dol) store, a `MutableMapping` of path to text. By default it is a local folder, `~/.local/share/ideadump` (or `$IDEADUMP_DATA_DIR`). Each idea is a folder:
+
+```
+README.md                         # the index: newest first, then by tag (generated)
+ideas/2026-11-14-idea-dump/
+    idea.json                     # the record: words (verbatim), title, summary, tags, status, research, links
+    README.md                     # the idea's page (generated)
+    research/2026-11-14-light.md  # research notes, never overwritten
+```
+
+The pages are generated from the records on every write, so the folder reads well in a file browser or on GitHub.
+
+### Syncing to a private git repository
+
+```bash
+pip install 'ideadump[git]'
+ideadump sync-init you/my-ideas     # creates the repository PRIVATE if missing, and makes the data folder its checkout
+ideadump sync                              # pull, commit everything, push
+ideadump sync-status
+```
+
+The git work is [acquaint](https://github.com/thorwhalen/acquaint)'s guarded sync: it refuses a repository that is not private, and a pre-push hook re-checks the remote and its visibility on every push. `sync-init` adopts an existing ideas folder (and refuses one that is a checkout of another repository); on a second machine, clone the repository into the data folder first. Generated pages are marked in `.gitattributes` so they never conflict: `sync` rebuilds them from the merged records after each rebase. A private repository is access control, not encryption.
+
+## Python
+
+Every verb is a plain function returning a JSON-able dict, and takes the store as `files`, so any `MutableMapping` works (a `dict` in tests, another `dol` store elsewhere):
+
+```python
+from ideadump import add, find, note
+
+files = {}
+r = add("offline speech to text on the phone", tags="audio", files=files)
+note(r["id"], text="# Prior art\n\nWhisper.cpp, Vosk.", files=files)
+find("speech recognition", files=files)["hits"]
+```
+
+`find` ranks with BM25 (standard library); pass `score=` to plug in another scorer, such as a semantic one.
+
+## Agent skill
+
+The skill lives in the package at `ideadump/data/skills/ideadump/SKILL.md`. For Claude Code, with the package installed, link it into your skills folder:
+
+```bash
+ln -s "$(python -c 'import ideadump, pathlib; print(pathlib.Path(ideadump.__file__).parent / "data/skills/ideadump")')" ~/.claude/skills/ideadump
+```
+
+Then tell any session "idea for later: ..." and it captures it. Other agent hosts read the same file; point yours at that folder (with the `gh skill` extension, `gh skill install thorwhalen/ideadump ideadump`).

ideadump-0.0.2/README.md

@@ -0,0 +1,72 @@
+# ideadump
+
+A place to dump ideas: capture them in your own words, research them a little, index and relate them, and find them again.
+
+```bash
+pip install ideadump
+```
+
+You tell an agent an idea in passing; it runs one command to keep it, verbatim, and a light research pass to see what it is called, what already exists and whether it is promising. Later you ask what ideas you have about something, or whether anything you have been working on relates to them.
+
+```bash
+ideadump add "a place to dump ideas, and do a bit of research on them" --title "Idea dump" --tags "tools, notes" --source my-session
+ideadump note idea-dump --file light-research.md --depth light     # attach research notes
+ideadump find "note taking research"                                # ranked, with the shared words
+ideadump find --file recent-work.md                                 # which ideas relate to this page of recent work?
+ideadump ls --status promising
+ideadump show idea-dump
+```
+
+Research is done by the agent with whatever search tools it has, so it sends queries (generic terms, not your notes) to outside services; the ideas themselves stay in your store.
+
+The primary user is an agent: the package ships a skill, `ideadump`, that tells it when and how to use these verbs (capture, light and deep research, linking, the "is my recent work related to my ideas" pass). See [Agent skill](#agent-skill).
+
+## Where ideas live
+
+Ideas are kept in a [dol](https://github.com/i2mint/dol) store, a `MutableMapping` of path to text. By default it is a local folder, `~/.local/share/ideadump` (or `$IDEADUMP_DATA_DIR`). Each idea is a folder:
+
+```
+README.md                         # the index: newest first, then by tag (generated)
+ideas/2026-11-14-idea-dump/
+    idea.json                     # the record: words (verbatim), title, summary, tags, status, research, links
+    README.md                     # the idea's page (generated)
+    research/2026-11-14-light.md  # research notes, never overwritten
+```
+
+The pages are generated from the records on every write, so the folder reads well in a file browser or on GitHub.
+
+### Syncing to a private git repository
+
+```bash
+pip install 'ideadump[git]'
+ideadump sync-init you/my-ideas     # creates the repository PRIVATE if missing, and makes the data folder its checkout
+ideadump sync                              # pull, commit everything, push
+ideadump sync-status
+```
+
+The git work is [acquaint](https://github.com/thorwhalen/acquaint)'s guarded sync: it refuses a repository that is not private, and a pre-push hook re-checks the remote and its visibility on every push. `sync-init` adopts an existing ideas folder (and refuses one that is a checkout of another repository); on a second machine, clone the repository into the data folder first. Generated pages are marked in `.gitattributes` so they never conflict: `sync` rebuilds them from the merged records after each rebase. A private repository is access control, not encryption.
+
+## Python
+
+Every verb is a plain function returning a JSON-able dict, and takes the store as `files`, so any `MutableMapping` works (a `dict` in tests, another `dol` store elsewhere):
+
+```python
+from ideadump import add, find, note
+
+files = {}
+r = add("offline speech to text on the phone", tags="audio", files=files)
+note(r["id"], text="# Prior art\n\nWhisper.cpp, Vosk.", files=files)
+find("speech recognition", files=files)["hits"]
+```
+
+`find` ranks with BM25 (standard library); pass `score=` to plug in another scorer, such as a semantic one.
+
+## Agent skill
+
+The skill lives in the package at `ideadump/data/skills/ideadump/SKILL.md`. For Claude Code, with the package installed, link it into your skills folder:
+
+```bash
+ln -s "$(python -c 'import ideadump, pathlib; print(pathlib.Path(ideadump.__file__).parent / "data/skills/ideadump")')" ~/.claude/skills/ideadump
+```
+
+Then tell any session "idea for later: ..." and it captures it. Other agent hosts read the same file; point yours at that folder (with the `gh skill` extension, `gh skill install thorwhalen/ideadump ideadump`).

ideadump-0.0.2/ideadump/__init__.py

@@ -0,0 +1,51 @@
+"""ideadump: a place to dump ideas, research them a little, and find them again.
+
+Capture an idea in the owner's own words, attach research notes (a light pass at
+capture, a deep one when it looks promising), tag and link ideas, and ask which ideas
+relate to a query or to a page describing recent work. Ideas live in a ``dol`` store,
+by default a local folder, optionally a checkout of a private git repository.
+
+>>> from ideadump import add, find
+>>> files = {}
+>>> _ = add("Offline speech to text on the phone", tags="audio", files=files)
+>>> find("speech recognition", files=files)["hits"][0]["tags"]
+['audio']
+
+The command line (``ideadump --help``) and the agent skill shipped in
+``ideadump/data/skills/ideadump`` drive the same verbs.
+"""
+
+from ideadump.base import IdeadumpError
+from ideadump.store import data_dir, text_files
+from ideadump.sync import sync, sync_init, sync_status
+from ideadump.tools import (
+    TOOLS,
+    add,
+    find,
+    link,
+    ls,
+    note,
+    reindex,
+    show,
+    update,
+    where,
+)
+
+__all__ = [
+    "IdeadumpError",
+    "TOOLS",
+    "add",
+    "data_dir",
+    "find",
+    "link",
+    "ls",
+    "note",
+    "reindex",
+    "show",
+    "sync",
+    "sync_init",
+    "sync_status",
+    "text_files",
+    "update",
+    "where",
+]

ideadump-0.0.2/ideadump/__main__.py

@@ -0,0 +1,73 @@
+# PYTHON_ARGCOMPLETE_OK
+"""``ideadump`` on the command line: every verb of :data:`ideadump.tools.TOOLS`.
+
+    ideadump add "the owner's words, verbatim" --title "Short title" --tags "a, b" --source my-session
+    ideadump note <id> --file research.md --depth light
+    ideadump find "offline speech to text"          # or --file recent-work.md
+    ideadump ls --status promising
+    ideadump show <id>
+    ideadump sync
+
+``--json`` as the last argument prints the whole result instead of its text. Exit status is 0 on
+success and 1 on an error, whose message says what to do next.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import sys
+
+import cw
+
+from ideadump import tools
+from ideadump.base import IdeadumpError
+
+
+def _command(func):
+    func = tools.without(func)
+
+    @functools.wraps(func)
+    def command(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except IdeadumpError as error:
+            raise cw.CommandError(str(error)) from error
+
+    return command
+
+
+def _egress(as_json):
+    def egress(result, *, out, err):
+        if as_json or not isinstance(result, dict):
+            print(
+                json.dumps(result, indent=2, ensure_ascii=False, default=str), file=out
+            )
+        else:
+            print(result.get("text", ""), file=out)
+        return 0
+
+    return egress
+
+
+def main(argv=None):
+    """Run the command line. The ``ideadump`` console script."""
+    for stream in (sys.stdout, sys.stderr):
+        getattr(stream, "reconfigure", lambda **_: None)(errors="backslashreplace")
+    argv = list(sys.argv[1:] if argv is None else argv)
+    as_json = bool(argv) and argv[-1] == "--json"
+    if as_json:
+        argv = argv[:-1]
+    commands = {f.__name__.replace("_", "-"): _command(f) for f in tools.TOOLS}
+    code = cw.dispatch(
+        commands,
+        argv,
+        prog="ideadump",
+        convention=cw.MODERN,
+        egress=_egress(as_json),
+    )
+    raise SystemExit(code)
+
+
+if __name__ == "__main__":
+    main()

ideadump-0.0.2/ideadump/base.py

@@ -0,0 +1,38 @@
+"""Errors and constants shared across ideadump.
+
+An idea is one folder in the store, ``ideas/<id>/``, holding its record
+(``idea.json``, the single source of truth), a rendered ``README.md`` that a person
+reads on GitHub or a phone, and its research notes under ``research/``. Nothing here
+depends on any other module.
+"""
+
+from __future__ import annotations
+
+APP_NAME = "ideadump"
+DATA_DIR_ENVVAR = "IDEADUMP_DATA_DIR"
+
+IDEAS_DIR = "ideas"
+RECORD_FILE = "idea.json"
+README_FILE = "README.md"
+RESEARCH_DIR = "research"
+
+#: Where an idea stands. ``new`` on capture; the owner (or an agent relaying the
+#: owner's words) moves it on. ``promising`` is the cue for a deeper research pass.
+STATUSES = ("new", "promising", "parked", "pursued", "dropped")
+
+#: How deep a research note went. ``light`` is the pass made at capture (minutes, a
+#: few sources); ``deep`` is a full ``do-research``-style report.
+DEPTHS = ("light", "deep")
+
+
+class IdeadumpError(Exception):
+    """An error whose message says what to do next."""
+
+
+def record_key(idea_id: str) -> str:
+    """The store key of an idea's record.
+
+    >>> record_key("2026-11-14-an-idea")
+    'ideas/2026-11-14-an-idea/idea.json'
+    """
+    return f"{IDEAS_DIR}/{idea_id}/{RECORD_FILE}"

ideadump-0.0.2/ideadump/data/skills/ideadump/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ideadump
+description: Capture an idea the owner tells you, in their own words, research it a little (more if it looks promising), tag and link it, and find it again later, with the ideadump command. Use whenever the owner shares an idea unrelated to the current task or asks you to keep one ("I have an idea", "idea:", "jot this down", "dump this idea", "note this idea for later", "remind me of this idea"), asks about their ideas ("what ideas do I have about X", "list my ideas", "show the idea about Y", "research that idea deeper", "that one is promising", "park that idea"), or asks whether anything they have been working on relates to their ideas ("is any of my recent work related to my ideas", "anything in my ideas worth doing now"), typically during spare token budget. Ideas are stored in a local folder or a private git repository, never in the current project.
+license: MIT
+metadata:
+  audience: users
+---
+
+# ideadump: a place to dump ideas, and find them again
+
+The owner tells you an idea in passing, often in a session that has nothing to do with it, often dictated. Your job: keep it **in their words**, make it findable, give it a first look, and get out of the way. One command captures it; everything else is optional and cheap.
+
+**First, is it for the current task?** An idea about the work in front of you ("I have an idea: do X this way") is an instruction: act on it, do not dump it. Dump only ideas meant for later or for something else, or when the owner says to keep it.
+
+Ideas live in ideadump's data folder (`ideadump where`), never in the project you are working in. If that folder is a checkout of a private repository, `ideadump sync` pushes; otherwise it is local only, which is fine.
+
+## Capture (always)
+
+```bash
+ideadump add "<the owner's words, verbatim>" --title "<short title>" --summary "<your clean reading>" --tags "<tag>, <tag>" --source "<this session's name>"
+```
+
+- **Words verbatim**, dictation slips included. Never "fix" them in `words`; put your reading in `--summary`, and when you resolved a slip say so there ("'attic system' read as 'agentic system'"). If a slip changes the meaning and you cannot tell, ask one short question.
+- **Title**: five words or fewer, the thing itself ("Idea dump tool", not "An idea about ideas").
+- **Tags**: two to four, lowercase, reused from existing ones where they fit: `ideadump ls` shows the tags in use. Prefer the domain (`audio`, `fleet`, `writing`) and the kind (`tool`, `essay`, `research-question`, `business`).
+- Then `ideadump find "<title and summary>"` (the new idea is among the hits; ignore its own id): if an earlier idea is the same or close, `ideadump link <id> <other> --why "<one line>"` (or tell the owner it is a duplicate and ask whether to merge).
+- Reply to the owner in two lines at most: the id and title, and that a light look follows (or what it found).
+
+**In a session that must keep its context small** (a lookout or switchboard session, or the middle of an unrelated task): run the `add` yourself, then hand the light research to a subagent with the id and these instructions, and carry on with what you were doing.
+
+## Light research (at capture, a few minutes)
+
+Search with the field's generic terms, not the owner's sentences: their words stay in the store, and outside search services see only queries.
+
+Answer four questions, with sources, in a short Markdown note:
+
+1. **What is this called?** The standard name for the idea or its field, if there is one.
+2. **What exists already?** Prior art: tools, libraries, papers, products; one line each with a link. If you can search the owner's own packages and skills (in their fleet: `ir discover packages "<two phrasings>"`, `ir discover skills ...`), say what they already have.
+3. **What is the crux?** The one thing that would make it hard, or the one thing that makes it easy.
+4. **Verdict**: `promising`, `worth a deeper look`, `exists already (use X)`, or `park`, with one sentence of why.
+
+References Vancouver style (`[1]`, `[2]` with a REFERENCES list, `[name](url)` links). Then:
+
+```bash
+ideadump note <id> --file <note.md> --depth light
+ideadump update <id> --status promising     # only if the verdict says so; parked/dropped likewise
+ideadump sync
+```
+
+Write the note in a temporary folder, not in the current project.
+
+## Deep research (on request, or when the owner agrees an idea is promising)
+
+Load the `do-research` skill and run it on the idea at deep depth (its report shape, its Vancouver references). Store the report with `ideadump note <id> --file <report.md> --depth deep`, then `ideadump sync`. The report is as private as the idea. If the owner reads on a phone, give them a link only to a destination that is private and access-controlled (in their fleet, `annals publish`, whose links are private; or the idea's page in the private data repository). Never publish it anywhere public.
+
+## Finding ideas
+
+```bash
+ideadump ls                                 # newest first; --tag, --status, --limit
+ideadump show <id or part of it>            # the idea's page: words, summary, research, links
+ideadump find "offline speech recognition"  # ranked, with the words each hit shares with the query
+```
+
+The data folder is browsable as it is: `README.md` at its root is the index (newest first, then by tag), and each `ideas/<id>/README.md` is an idea's page, so on GitHub the owner can read it from a phone.
+
+## "Is anything I have been working on related to my ideas?"
+
+1. Gather a page of text describing recent work into a temporary file: what the owner's sessions did lately (in their fleet: `crowsnest ledger` for the per-session ledgers, `ol` for open loops), recent issue and PR titles, recent commit subjects (`git log --since=7.days --format=%s` in the active repositories). A few hundred lines is fine.
+2. `ideadump find --file <that file> --limit 15`.
+3. The ranking is lexical, so **judge it**: read the top hits' pages (`ideadump show`), keep only those that really relate, and tell the owner, for each, which idea, which work, and the one thing the work could do for the idea (or the idea for the work). Say plainly when nothing relates.
+4. Record a real connection: `ideadump update <id> --add-tags <project>` or a line in a research note.
+
+## Other verbs
+
+`ideadump update <id> --title/--summary/--tags/--add-tags/--status`, `ideadump link <a> <b> --why ...`, `ideadump reindex` (regenerate the pages), `ideadump sync-status`, `ideadump sync-init <owner>/<name>` (make the data folder a checkout of a private repository, created private if missing; an existing ideas folder is adopted). `--json` as the last argument of any verb prints the full result. Statuses: `new`, `promising`, `parked`, `pursued`, `dropped`.
+
+## Never
+
+- Never edit `words`; never delete an idea or a note the owner did not ask you to delete.
+- Never put idea text in the current project, an issue, or anywhere public. If ideadump refuses because the data folder is inside another git work tree, tell the owner; never set `IDEADUMP_ALLOW_INSIDE_WORK_TREE` yourself.
+- Never run deep research unasked on every idea: a light look at capture, deeper only on request or agreement.