Aftermark

Save what works. Teach your agent when to use it.

简体中文 · Download current release · MIT

A local bookmark library for coding agents. Keep a source, why you saved it, the project it applies to, and corrections from real work. Your browser, CLI and MCP-compatible agent share one collection.

1.0 release: collect → find → read → decide → record → correct, plus editing, archive/restore and portable backups. Import and manage sources from the app, CLI or agent. Every advertised operation is implemented; there are no placeholder feature controls.

Start in three steps

Requires Python 3.11+. Download the source ZIP, extract it, then:

1. Open http://127.0.0.1:43821, save a note or import the three examples.

2. In Connect an agent, copy the Codex setup command or your host's MCP configuration.

3. Choose the exact project name, generate its instructions and add them to your agent's project rules. Try a relevant task and inspect what it actually used.

Empty project means personal/global bookmarks only. Generating instructions changes no host files. Automatic recall depends on your host and instructions.

No account or extra model API key is needed for Aftermark. Installation and fetching webpages need internet; local notes, PDFs and keyword search work offline afterward. The project is not published to PyPI: use the source ZIP or the wheel on the release page.

Related MCP server: bookmark-mcp

What you can keep

Search finds task keywords in sources and applicable corrections. Read the matching page or subtitle segment, then decide with your agent whether it fits the project. Usage records distinguish referenced, applied, verified and skipped; changed sources leave older evidence clearly marked. A usage record must include the revision actually read. If the source changes during the task, reread its content and corrections and reassess before recording.

Long sources now show a passage covering more distinct task keywords, rather than stopping at the first generic match. PDF pages, subtitle timestamps and original text offsets remain available. This improves where you start reading; applicability is still your agent's judgment.

Connect and use

In an activated environment:

aftermark --data-dir .local/library config --project my-game
aftermark --data-dir .local/library connect codex
aftermark --data-dir .local/library connect codex --apply

The first command generates project-specific instructions. The next previews Codex registration; --apply registers it through Codex's CLI and preserves conflicting entries. Other MCP hosts use the generated JSON. The ten MCP tools cover source import, browsing, reading, editing, correction, usage and archive/restore.

Ask your agent to import an article or text PDF URL into a named project. import_url fetches the source and saves it; the agent must still retrieve and read it before citing it. The local app and add --url URL --fetch use the same importer. HTML/text is limited to 5 MB, PDFs to 20 MB. Video URLs remain link-only unless you supply subtitles.

Agents can import local PDF/MD/TXT/SRT/VTT through import_file, edit a revision they read with update_bookmark, browse with list_bookmarks, and archive or restore with set_archived. CLI equivalents are add --file, edit --revision, list and archive --restore. Originals and history remain intact.

Upgrade to 1.0: back up, rerun setup, restart services, refresh the page and reload MCP. Editing now also requires expected_revision: HTTP PUT without it returns 422; a stale revision returns 409 without overwriting content. The updated UI sends it automatically and keeps conflicting drafts. Usage records still require their read revision. Existing data and backups are unchanged. Daily use, upgrades and recovery.

Codex setup and real-client evidence · CLI and source reading

Does it work?

74 Python tests and 7 DOM/API integration checks cover the local workflow, including concurrent editing, draft preservation, source import and backup recovery. Real Codex reviews use an isolated library and report actual code checks; historical CLI and desktop tool evidence is retained. Full interactive browser acceptance, other hosts and macOS/Linux execution remain unverified. The tests do not establish reliable spontaneous recall or productivity gains. Exact validation scope.

Your data

The launchers use .local/library inside the project. Use --data-dir .local/library from this directory to access it from the CLI. Without that flag, the default is %LOCALAPPDATA%\Aftermark on Windows, ~/Library/Application Support/Aftermark on macOS, or $XDG_DATA_HOME/aftermark on Linux. AFTERMARK_HOME can also select a directory. All clients must use the same library.

JSON export/import includes original files and history. Existing IDs are skipped on import. Back up before upgrades; schema 2 and JSON backup format 1 remain unchanged in this release. The app is for personal, local use and binds to loopback.

Limits

Keyword retrieval, not semantic search. No OCR, automatic video transcription, frame understanding or cloud sync. Web extraction does not execute JavaScript or bypass login. Usage evidence is submitted by the user or agent; Aftermark does not independently verify it. Sources remain references and cannot override higher-priority instructions.

Development

python -m pip install -e ".[dev]"
python -m pytest
python -m build

Python, SQLite, FastAPI, the official MCP SDK and plain browser JavaScript. Architecture · Feature checklist · Changelog.

Contributing and optional UI-script checks.

MIT. Example notes are original project content. Imported sources retain their original rights.