#+OPTIONS: num:nil

Promnesia is a browser extension for [[https://chrome.google.com/webstore/detail/promnesia/kdmegllpofldcpaclldkopnnjjljoiio][Chrome]]/[[https://addons.mozilla.org/en-US/firefox/addon/promnesia][Firefox]] (including Firefox for Android!) which serves as a web surfing copilot, enhancing your browsing history and web exploration experience.

TLDR: it lets you explore your browsing history in context: where you encountered it, in chat, on Twitter, on Reddit, or just in one of the text files on your computer. This is unlike most modern browsers, where you can only see when you visited the link.

It allows you to answer different questions about the current web page:

#+html: <span id="questions"><span>

have I been here before? When? [[https://karlicoss.github.io/promnesia-demos/child-visits.webm][demo (30 s)]] [[https://karlicoss.github.io/promnesia-demos/child-visits-2.webm][demo (40s)]]
how did I get on it? Which page has led to it? [[https://karlicoss.github.io/promnesia-demos/how_did_i_get_here.webm][demo (40s)]]
why have I bookmarked it? who sent me this link? Can I just jump to the message? [[https://karlicoss.github.io/promnesia-demos/watch_later.webm][demo (30s)]]
or, can I jump straight into the file where the link occurred? [[https://karlicoss.github.io/promnesia-demos/jump_to_editor.webm][demo (20s)]]
which links on this page have I already explored? [[https://karlicoss.github.io/promnesia-demos/mark-visited.webm][demo (30s)]],
which posts from this blog page have I already read? [[https://karlicoss.github.io/promnesia-demos/mark-visited-2.webm][demo (20s)]]
have I annotated it? [[https://karlicoss.github.io/promnesia-demos/highlights.webm][demo (1m)]]
how much time have I spent on it? [[https://user-images.githubusercontent.com/291333/82124084-ba040100-9794-11ea-9af9-ee250ebbb473.png][screenshot]]
and it also works on your phone! [[https://karlicoss.github.io/promnesia-demos/mobile/panel-jbor.png][screenshot]]

See [[file:doc/GUIDE.org#extension-features][feature guide]] for more information.

You can jump straight to the [[#demos][Demos]] and [[#install][Install]] sections if you're already overexcited.

Motivation See a [[https://beepb00p.xyz/promnesia.html][writeup]] on history and the problems Promnesia is solving. Here's a short summary.

Has it ever occurred to you that you were reading an old bookmark or some lengthy blog post and suddenly realized you had read it already before? It would be fairly easy to search in the browser history, however, it is only stored locally for three months.
TODO link?
Or perhaps you even have a habit of annotating and making notes elsewhere? And you wanna know quickly if you have the current page annotated and display the annotations. However, most services want you to use their web apps even for viewing highlights. You don't know if you have highlights, unless you waste time checking every page.
Or you have this feeling that someone sent you this link ages ago, but you don't remember who and where.
Or you finally got to watch that thing in your 'Watch later' youtube playlist, that's been there for three years, and now you want to know why did you add it in the first place.

Then this tool is for you.

#+html: <div id="demo"><div>

Demos :PROPERTIES: :CUSTOM_ID: demos :END:

See [[file:doc/GUIDE.org#extension-features][feature guide]] if you're wondering how something specific here works.

[[https://karlicoss.github.io/promnesia-demos/screens/promnesia andy Screenshot at 2020-06-05 23-33-07.png]]
- a green eye means that the link was visited before and has some [[#glossary][contexts]], associated with it. When you click on it, the sidebar opens with more information about the visits.
- You can see that I've sent the link to Jane on Telegram (#1)
- I've annotated the link on Instapaper and highlights (#3) is marked with yellow right within the page
  
  Normally in order to see see your Instapaper highligths you have to go to the web app first!
- I've clipped some content to my personal notes at some point (#8), the selected text was matched and highlighted as well
  
  If I click =notes/ip2org.org=, it will cause my Emacs to open and jump to the file, containing this note.
  
  and jump straight to the clipping within the file. -- TODO
[[https://karlicoss.github.io/promnesia-demos/screens/promnesia universal love Screenshot at 2020-06-05 23-18-38.png]]
- I have a note about the page in my personal notes on my filesystem (#2)
- I chatted with a friend and sent them the link at some point (#6)
  
  Clicking on the link will open Telegram and jump straight to the message where the link was mentioned. So you can reply to it without having to search or scroll over the whole chat history.
  
  Json is clearly not the most convenient way to go through conversations with friends, but that's a matter of representing chats in a plaintext form. The benefit though is that once you have any sort of grepable source it's super easy to feed it into the plugin.
- I've tweeted about this link before (#11)
  
  Similarly, clicking would jump straight to my tweet.
- I also have this link annotated via [[https://hypothes.is][Hypothesis]] (#4, #12, #13)
Annotated demo of sidebar with direct & child visits, and 'visited' marks (click to zoom) #+html: <img src="https://karlicoss.github.io/promnesia-demos/screens/visits_childvisits_locator_popups_boring_interesting.png"></img>
Annotated demo of highlight and locator features (click to zoom) #+html: <img src="https://karlicoss.github.io/promnesia-demos/screens/highlights_filelinks_locator.png"></img>
More:
- A [[https://www.youtube.com/watch?v=9PsOeYheIY4][video]], demonstrating
  - [[file:doc/GUIDE.org#mark-visited]['mark visited']] feature
  - highlights
  - jumping to the originating tweet; jumping straight to the org-mode heading where links occurred
- You can find more short screencasts, demonstrating various features [[https://github.com/karlicoss/promnesia-demos][here]]
- There are more screenshots [[https://github.com/karlicoss/promnesia/issues/5#issuecomment-619365708][here]]
- This [[https://beepb00p.xyz/myinfra-roam.html#promnesia][post]] features a video demo of using Promnesia with a Roam Research database
- Video demos for the mobile extension:
  - [[https://karlicoss.github.io/promnesia-demos/mobile/panel-w3c.webm][showing all references to pages on W3C website in my org-mode notes]]
  - [[https://karlicoss.github.io/promnesia-demos/mobile/mark-visited-reddit.webm][marking already visited links on the page]], to make easier to process Reddit posts

How does it work? :PROPERTIES: :CUSTOM_ID: how-does-it-work :END: Promnesia consists of three parts:

browser extension
- neatly displays the history and other information in a sidebar
- handles highlights
- provides search interface
However, browser addons can't read access your filesystem, so to load the data we need a helper component:
server/backend: =promnesia serve= command

It's called 'server', but really it's just a regular program with the only purpose to serve the data to the browser. It runs locally and you don't have to expose it to the outside.
indexer: =promnesia index= command

Indexer goes through the sources (specified in the config), processes raw data and extracts URLs along with other useful information.

Another important thing it's doing is normalising URLs to establish equivalence and strip off garbage. I write about the motivation for it in [[https://beepb00p.xyz/promnesia.html#urls_broken]["URLs are broken"]].

You might also want to skim through the [[https://github.com/karlicoss/promnesia#glossary][glossary]] if you want to understand deeper what information Promnesia is extracting.

** Data sources Promnesia ships with some builtin sources. It supports:

data exports from online services: Reddit/Twitter/Hackernews/Telegram/Messenger/Hypothesis/Pocket/Instapaper, etc.

It heavily benefits from [[https://github.com/karlicoss/HPI][HPI]] package to access the data.
Google Takeout/Activity backups
Markdown/org-mode/HTML or any other plaintext on your disk
- for ex. local personal knowledge bases - Logseq ([[file:doc/config.py#L67][example config]]), Obsidian
in general, anything that can be parsed in some way
you can also add [[https://github.com/karlicoss/promnesia/blob/master/doc/SOURCES.org#extending][your own custom sources]], Promnesia is extensible

See [[https://github.com/karlicoss/promnesia/blob/master/doc/SOURCES.org][SOURCES]] for more information.

** Data flow

Here's a diagram, which would hopefully help to understand how data flows through Promnesia.

See HPI [[https://github.com/karlicoss/HPI/blob/master/doc/SETUP.org#data-flow][section on data flow]] for more information on HPI modules and data flow.

Also check out my [[https://beepb00p.xyz/myinfra.html#promnesia][infrastructure map]], which is more detailed!

: ┌─────────────────────────────────┐ ┌────────────────────────────┐ ┌─────────────────┐ : │ 💾 HPI sources │ │ 💾 plaintext files │ │ other sources │ : │ (twitter, reddit, pocket, etc.) │ │ (org-mode, markdown, etc.) │ │ (user-defined) │ : └─────────────────────────────────┘ └────────────────────────────┘ └─────────────────┘ : ⇘⇘ ⇓⇓ ⇙⇙ : ⇘⇘ ⇓⇓ ⇙⇙ : ┌────────────

Promnesia

Install / Use

README

TODO link?

and jump straight to the clipping within the file. -- TODO

Json is clearly not the most convenient way to go through conversations with friends, but that's a matter of representing chats in a plaintext form. The benefit though is that once you have any sort of grepable source it's super easy to feed it into the plugin.