kyle/exo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restart with Claude

Browse Source
This commit is contained in:
Kyle Isom
2026-03-20 11:54:56 -07:00
parent 02a6356158
commit ea32237279
27 changed files with 1400 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/KExocortex/About.md Normal file
View File

@@ -0,0 +1,42 @@
%%
Title: About my exocortex
Created: 2022-03-07 17:09
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# About my exocortex
I've been on the lookout for the knowledge management system that fits my needs
for a while.
## Background
The first time I really started to try to keep a personal knowledge management
system was a [[Resources/PKM/Software/CFofTF|pile of notes]] files. I had a script called "today":
```
#!/bin/sh
vim $HOME/notes/"$(date +'%Y%m%d').txt"
```
Relatively straightforward, but there was no structure and no linking between text files. Then I got introduced to [[Resources/PKM/Software/Evernote|Evernote]] by someone who was an [[Resources/PKM/Software/Evernote|Evernote]] devotee; she got me to try it and I was hooked. I liked that it was available on *every* damn platform I had; to be fair, I was using OS X at the time so there was that. Switching to Linux made it a lot less palatable, plus it's closed source so I couldn't fix bugs or tweak things to do what I wanted.
One feature I *really* liked was the clipper: you could throw anything into your space. [[Resources/PKM/Software/Dendron|Dendron]] sort of has this, but it's not great. [[Resources/PKM/Software/Obsidian|Obsidian]] works similarly.
Later on, I started using a little Macbook Air and found a program called [[Resources/PKM/Software/Quiver|Quiver]] there. It's great, although OS X only. I don't think you could attach files, but it had a neat cell-based structure that worked well.
Then I found [[Resources/PKM/Software/Notion|Notion]], which promised to be an [[Resources/PKM/Software/Evernote|Evernote]] alternative. There wasn't a Linux desktop client, though, and you had to be online to use it. Also, the UI was far clunkier than Evernote, and Evernote's wasn't special. Finally, I tried [[Resources/PKM/Software/OrgMode|org-mode]], but again, maintaining artifacts was hard.
I moved onto [[Resources/PKM/Software/Dendron|Dendron]] next, but I knew it was going to be a stopgap for the next thing. Probably a long-term stopgap, but not meant to be permanent. Dendron, fortunately, had a lot going for it. I think I stayed with it for just over a year before making the leap to [[Resources/PKM/Software/Obsidian|Obsidian]].
## What do I want
If I think back about the features I want, I like having the ability to drop documents and write notes about them, I like having access from across a lot of devices, and I liked the cell structure from [[Resources/PKM/Software/Quiver|Quiver]]. I liked how [[Resources/PKM/Software/Dendron|Dendron]] had a simple hierarchy, easy linking, and great navigation. Roll all that up, and that's my personal knowledge base. [[Resources/PKM/Software/Obsidian|Obsidian]] works similarly.
A litmus test I like to use is that trying to remember the [[Resources/Career/Camerata|Camerata]] article. In an ideal world, I'd have a readable (e.g. instapaper-style output) dump of the page alongside the notes I took. I'd be able to dump this out in either HTML (to put online) or as a PDF so I could share it with other people. I traditionally struggled with what the name of the Camerata was, so being able to find it was sometimes hard. You'd think it would be easy with grep, but it's hard to encode that into a regex. It'd be nice to have search results that return things within a small edit distance if there's not a lot of result.
My thinking around how to store artifacts has been influenced by my experiments with [[Resources/Computing/Programming/Notebook/Ideas/Nebula|building a content-addressable data store]] and a general [[Archive/Computing/FObj|file server]].

29
docs/KExocortex/Adjacent.md Normal file
View File

@@ -0,0 +1,29 @@
%%
Title: Adjacent projects
Created: 2022-03-07 17:23
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# Adjacent projects
What projects are adjacent to this space?
## Knowledge management systems
* [[Resources/PKM/Software/Dendron]]
* [[Resources/PKM/Software/Obsidian]]
* [[Resources/PKM/Software/Evernote]]
* [Roam Research](https://roamresearch.com/)
* [[Resources/PKM/Software/Notion]]
## Artifact storage
- [[Resources/Computing/Datastore/Upspin]] provides a global name space to name all your files.
* [[Resources/Computing/Datastore/Perkeep]]
#### General storage ideas
- [[202203071715 Content-Addressable Store]]

20
docs/KExocortex/Agents.md Normal file
View File

@@ -0,0 +1,20 @@
%%
Title: Exocortex agents
Created: 2022-03-08 01:26
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# Exocortex agents
In addition to the knowledge graph (aka what I think of as kExocortex), I also plan on installing Huginn on the pi4 desktop and seeing what else I need to get running.
* What machine should I set this up on?
* Preference is for local hardware.
* I have the [[Resources/Computing/Ambient/Platform/RaspberryPi|Raspberry Pi]] but this is likely to be particularly slow.
* Maybe I can use a spare laptop I have lying around.
* It needs tailscale.
#FollowUp exocortex as second brain vs exocortex as computational extension of the self.

17
docs/KExocortex/Artifacts/WebPages.md Normal file
View File

@@ -0,0 +1,17 @@
%%
Title: Dealing with webpages
Created: 2022-03-08 01:33
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# Dealing with webpages
Ideally, storing a URL stores a snapshot of the page.
* [A web extension that saves a complete web page into a single HTML file](https://github.com/gildas-lormeau/SingleFile)

16
docs/KExocortex/Datastore.md Normal file
View File

@@ -0,0 +1,16 @@
%%
Title: Data storage
Created: 2022-03-08 01:34
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# Data storage
Data storage in kexocortex covers note and potentially artifact storage.
Metadata should go into a [[Resources/Computing/Database|database]], preferably [[Resources/Computing/Database/SQLite|SQLite]]. Artifact data (e.g. the blobs) should go into a [[202203071715 Content-Addressable Store]].
I had considered other systems (like [RavenDB](https://ravendb.net/), but that is a [[Resources/Computing/Lang/CSharp|C#]]-only [[Resources/Computing/Database|database]]).

68
docs/KExocortex/Elements.md Normal file
View File

@@ -0,0 +1,68 @@
%%
Title: Elements of an Exocortex
Created: 2022-03-05 21:09
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source: [[Archive/Computing/KExocortex/History]]
%%
The original source of this is the [[Archive/Computing/KExocortex/History|historical]] exocortex notes, and will be the most updated source of what I think constitutes a useful exocortex.
### The elements of exocortices
The elements of an exocortex, briefly touched on above and expanded
below, include
* artifacts,
* the artifact repository,
* notes,
* structure,
* a query interface,
* an exploratory interface,
* a presentation interface,
* an update interface,
* locality, and
* totality.
#### Artifacts
An artifact is any object that is not a textual writeup by me that should be referenceable as part of the exocortex. A copy of a paper from ArXiV might serve as an artifact. Importantly, artifacts must be locally-available. They serve as a snapshot of some source of knowledge, and should not be subject to link decay, future pay-walling (or loss of access to a pay-walled system), or loss of connectivity. An artifact should be timestamped: when was it captured? When was the artifact created upstream? An artifact must also have some associated upstream information --- how did it come to be in the repository?
#### The artifact repository
An artifact may be relevant to more than one field of interest; accordingly, all artifacts should exist in a central repository. This repository should support artifact histories (e.g. collecting updates to artifacts, where the history is important in capturing a historical view of knowledge), multiple formats (a book may exist in PDF, EPUB, or other formats), and a mechanism for exploring, finding, and updating docs. The repository must capture relevant metadata about each artifact.
#### Notes
A note is a written summary of a certain field. It should be in some rich-text format that supports linking as well as basic formatting. The ideal text format appears to be the org-mode format given its rich formatting and ability to transition fluidly between outline and full document; however, this may not be the final, most effective format. A note is the distillation of artifacts into an understandable form, providing avenues to discover specifics that may need to be held in working memory only briefly.
#### Structure
A structured format allows for fast and efficient knowledge lookups. It grants the researcher a starting place with a set of rules governing where and how things may be found. It imposes order over chaos such that relevant kernels of knowledge may be retrieved and examined in an expedient manner. The metaphor that humans seem to adapt to the most readily is a graph structure, particularly those that are generally hierarchical in nature.
#### A query interface
The exocortex and the artifact repository both require a query interface; they may be part of the same UI. A query UI allows a researcher to pose questions of the exocortex, directly looking for specific knowledge.
The four interfaces (query, exploration, presentation, and update) may all be facets of the same interface, and they may benefit from a cohesive and unified interface; however, it is important that all of these use cases are considered and supported.
#### An exploratory interface
The exploratory interface allows a researcher to meander through the knowledge store, exploring topics and potentially identifying new areas to push the knowledge sphere out further.
#### A presentation interface
The presentation interface allows a set of notes to be shared with others; it should be possible to include some or all artifacts associated with these notes. For example, it may not be appropriate to share a copy of a book with the presentation, but it may be appropriate to share a copy of some of the supporting papers.
#### An update interface
The update interface is where knowledge is added to the exocortex, whether through capturing an artifact or writing notes.
#### Locality
An exocortex must be localized to the user, with the full repository available offline. Quick input or scratch pad notes might be available, but realistically, the cost of cloud storage and the transfer sizes mean that having the full exocortex available is unlikely. Instead, a hybrid model allowing quick captures of knowledge available remotely combined with a full exocortex on a local system presents the probably best solution.
#### Totality
An exocortex represents the sum of the user's knowledge. There aren't separate exocortices for different areas. Everything I know should go into my exocortex.

12
docs/KExocortex/GraphDB.md Normal file
View File

@@ -0,0 +1,12 @@
%%
Title: GraphDB
Created: 2022-09-12 16:57
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# GraphDB
The notes in [[Archive/Computing/KExocortex|my exocortex]] should be organised in a [[Resources/Computing/Algorithms/Graph|graph]] format.

258
docs/KExocortex/History.md Normal file
View File

@@ -0,0 +1,258 @@
%%
Title: History
Created: 2022-09-12 16:58
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# History
## Original notes from my bullet journal
![](/assets/images/2022-02-23-01-27-01.png)
The original notes from my bullet journal that I took on my exocortex are found on page 109-110 of that journal; page 108 is journal entries for 2021-02-08 and 2021-02-16; page 111 starts with 2021-02-17. The first entry in the mercurial logs for the first pass I started last year was 2021-02-14.
* Goal
- Collect artifacts + notes → current knowledge
- Daily writeups
* Ex.
- Gemlog
- notes.org
- books/*.org
- PDF docs
* SCM is a red herring
* Evernote
- notes/folders
- clipper
- tags
- everything searchable
- synced (may be red herring)
* Quiver
- cell types
* Jupyter notebooks
- code
- markdown
* swolfram
- [archive](https://writings.stephenwolfram.com/2019/02/seeking-the-productive-life-some-details-of-my-personal-infrastructure/)
* Solution
- Minimal viable metadata
- Data
- Tags
- Artifact link
- Central artifact repo
- Hash/link
- Node type (article, notes, ...)
- Type: Node = Folder|Page|Artifact
- How to create a searchable index?
- Retain old copies
- Index header
- Date retrieved
- Doc ID
- Source
* Artifact header
- Needs to support history
- Doc ID
- Date retrieved / stored
- Artifact date
- Source
- Artifact type
- Tags
- Category
- Blobs
- Format
- Blob ID
* Central artifact repository
- Metadata index
- Blob store
- Upload interface
* Elements of an exocortex
- Artifacts
- Artifact repository
- Notes
- Structure
- UI
- Query
- Exploratory
- Presentation
- Update
- Locality
- Totality
## From a writeup
This is a rough draft on some thoughts about exocortices that has been simmering in the back of my mind lately. The catalyst for writing it was reading Stephen Wolfram's (with all caveats that come with reading his posts) entry "Seeking the Productive Life: Some Details of My Personal Infrastructure".
### Background
An exocortex is "a hypothetical artificial information-processing system that would augment a brain's biological cognitive processes." I have made many attempts at building my own, including
* A web-based wiki (including my own custom solution, gitit, MediaWiki, and others.
* Org-mode based notes, including my current notes/notes.org system (with subdirectories for other things such as book notes)
* Evernote / Notion
* The Quiver MacOS app
* Experimenting in building custom exocortex software (e.g. kortex)
* A daily weblog (e.g. the old ai6ua.net site) and gemlog to summarize important knowledge gained that day.
Each of these has their own shortcomings that don't quite match up with my expectations or desires. An exocortex must be a personalized system adapted to its user to maximise knowledge capture.
Succinctly put, the goal of an [exocortex](https://en.wiktionary.org/wiki/exocortex) is to collect artifacts and notes (including daily notes), organize them, and allow for written summaries of current snapshots of my knowledge. Put another way, "artifacts + notes + graph structure = exocortex". Note that a folder hierarchy is a tree, which is a form of directed graph. Symlinks inside a folder act as edges to notes outside of that folder, refining the graph structure.
This writeup is an attempt at characterising and exploring the exocortex problem space to capture my goals, serve as a foundation for the construction of such a system, and, through discussion of the problem space, tease out the structure of the problem to discover a closer approximation to the idealized reality of an exocortex system.
### The elements of exocortices
The elements of an exocortex, briefly touched on above and expanded below, include
* artifacts,
* the artifact repository,
* notes,
* structure,
* a query interface,
* an exploratory interface,
* a presentation interface,
* an update interface,
* locality, and
* totality.
#### Artifacts
An artifact is any object that is not a textual writeup by me that should be referenceable as part of the exocortex. A copy of a paper from ArXiV might serve as an artifact. Importantly, artifacts must be locally-available. They serve as a snapshot of some source of knowledge, and should not be subject to link decay, future pay-walling (or loss of access to a pay-walled system), or loss of connectivity. An artifact should be timestamped: when was it captured? When was the artifact created upstream? An artifact must also have some associated upstream information --- how did it come to be in the repository?
#### The artifact repository
An artifact may be relevant to more than one field of interest;
accordingly, all artifacts should exist in a central repository. This repository should support artifact histories (e.g. collecting updates to artifacts, where the history is important in capturing a historical view of knowledge), multiple formats (a book may exist in PDF, EPUB, or other formats), and a mechanism for exploring, finding, and updating docs. The repository must capture relevant metadata about each artifact.
#### Notes
A note is a written summary of a certain field. It should be in some rich-text format that supports linking as well as basic
formatting. The ideal text format appears to be the org-mode format given its rich formatting and ability to transition fluidly between outline and full document; however, this may not be the final, most effective format. A note is the distillation of artifacts into an understandable form, providing avenues to discover specifics that may need to be held in working memory only briefly.
#### Structure
A structured format allows for fast and efficient knowledge lookups. It grants the researcher a starting place with a set of rules governing where and how things may be found. It imposes order over chaos such that relevant kernels of knowledge may be retrieved and examined in an expedient manner. The metaphor that humans seem to adapt to the most readily is a graph structure, particularly those that are generally hierarchical in nature.
#### A query interface
The exocortex and the artifact repository both require a query
interface; they may be part of the same UI. A query UI allows a researcher to pose questions of the exocortex, directly looking for specific knowledge.
The four interfaces (query, exploration, presentation, and update) may all be facets of the same interface, and they may benefit from a cohesive and unified interface; however, it is important that all of these use cases are considered and supported.
#### An exploratory interface
The exploratory interface allows a researcher to meander through the knowledge store, exploring topics and potentially identifying new areas to push the knowledge sphere out further.
#### A presentation interface
The presentation interface allows a set of notes to be shared with others; it should be possible to include some or all artifacts associated with these notes. For example, it may not be appropriate to share a copy of a book with the presentation, but it may be appropriate to share a copy of some of the supporting papers.
#### An update interface
The update interface is where knowledge is added to the exocortex, whether through capturing an artifact or writing notes.
#### Locality
An exocortex must be localized to the user, with the full repository available offline. Quick input or scratch pad notes might be available, but realistically, the cost of cloud storage and the transfer sizes mean that having the full exocortex available is unlikely. Instead, a hybrid model allowing quick captures of knowledge available remotely combined with a full exocortex on a local system presents the probably best solution.
#### Totality
An exocortex represents the sum of the user's knowledge. There aren't separate exocortices for different areas. Everything I know should go into my exocortex.
### Exploring the problem space
In order to map out the structure of an exocortex, it's useful to review what has worked and what hasn't. Each alternative presented will consider what worked and what didn't to clarify what an effective exocortex looks like.
#### Git-backed wikis and plaintext folders
At a high-level, wikis like Gitit and folders of plain-text (including org-mode) data are roughly equivalent; the differences lie primarily in how they are presented. Neither approach works well for indexing or organizing artifacts, and while some approaches like a scanner that adds notes to a SQLite database (for improved search performance).
Using a folder of org-mode notes is probably one of the better note-taking interfaces that I have found; however, there is no notion of an artifact repository without considerable manual work.
The main downsides to this approach are the lack of good query and exploration UIs, along with the lack of a useful artifact repository. The upsides are good updates and presentation interfaces.
#### Evernote and Notion
Evernote (and also notion) provide a unified, searchable interface across multiple machines. Evernote in particular has a usable artifact repository, although information about upstream sources isn't available, nor are metadata about the object or the idea of multiple formats and history.
Evernote is a paid service, and neither is particularly extensible to a user's needs. Exploring the exocortex is difficult, as there's no notion of an entry point. Presenting nodes is met with some success, albeit limited.
#### Quiver
Quiver is an excellent note-taking application; however, it is
MacOS-only. It does have some ability to import web pages, but in general it lacks any idea of an artifact repository. The ability to intersperse different cell types is good.
#### Jupyter notebooks
Jupyter notebooks provide an excellent interface for interspersing computational ideas with prose; there is no notion of an artifact repository, however. Linking notebooks isn't supported, and there is no overall structure besides manual hyperlinking and a directory structure.
### The artifact repository
The artifact repository is one of the two pillars of the exocortex; it stores the "first hand" sources of knowledge.
#### The central index
The first part of an artifact repository is a central index that
provides
* references and linking to artifacts,
* a "blob" store that contains the artifacts, and
* some management interface that allows adding and editing metadata as
well as adding artifacts.
An artifact entry in the index contains, at a minimm,
* An artifact identifier
* Authorship information
The artifact identifier is used to associate all related artifacts (e.g. previous revisions, different formats, etc.)
#### Artifacts
An artifact consists of multiple components:
* A primary metadata entry that organizes artifacts
* Pointers to artifact "blobs"
* A historical record of changed blobs
The metadata header for an artifact should contain, at a minimum, fields for
* Artifact identifier
* A list of revisions
Each artifact can have zero or more blobs associated. For example, a physical book reference might not have a blob associated; an ebook might have multiple blobs corresponding to different formats; and a webpage snapshot may have mulitple blobs representing revisions to the page.
A blob header stores
* The artifact identifier
* The date retrieved or stored
* The date of the artifact itself
* The source
* Blob type information (e.g. a MIME type)
* A list of categories
* A list of tags
The headers should probably be stored in a database of some kind; SQLite is a good example for the first iteration. Blobs themselves will need to be stored on disk, probably in a format related to a hash of the blob contents, such as in a content-addressable store (CAS).
### The exocortex
The exocortex consists of a graph database that links notes. At a broad level, it should probably start with a root node that points to broad fields. The update interface should allow manipulation of nodes as graph nodes in addition to allowing for adding and editing notes. A node might be thought of as "type node = Note | ArtifactLink". That is, a note can link to other notes or to artifacts. A proper node title is the sum of the paths. For example, consider the following structure linked below:
![](/assets/images/2022-02-23-01-46-47.png)
Different possibilities for naming note3 include:
* root->note2->note3
* root=>note2=>note3
* root/note2/note3
Personally, I prefer the arrow notation with equal sign. Each note can be shortened to a partial path; e.g. "note2=>note3". The title for each note can be stored in a metadata entry.
### Next steps
A first step is to start constructing an artifact repository. Once this is in place, a suitable graph database (for example,
[cayley](https://github.com/cayleygraph/cayley)) should be identified, and an exocortex core developed. User interfaces will necessarily be developed alongside these systems.

24
docs/KExocortex/KnowledgeGraph.md Normal file
View File

@@ -0,0 +1,24 @@
%%
Title: Knowledge graph
Created: 2022-03-08 01:48
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# Knowledge graph
An exocortex is knowledge graph + repository store.
Thoughts:
* Node: entity in the graph
* Entity / attribute / value
* Relationship links (child, parent, sibling, related)
* Tags
* Links as nodes
* Model as protobuf?
## Reading list
* [Collective Intelligence at the Knowledge Graph Conference](https://deelythomas.medium.com/collective-intelligence-at-the-knowledge-graph-conference-6de36eb84e01)

53
docs/KExocortex/KnowledgeGraph/Tuple.md Normal file
View File

@@ -0,0 +1,53 @@
%%
Title: Datastore tuples
Created: 2022-03-08 01:45
Status:
Parent: [[Archive/Computing/KExocortex/KnowledgeGraph]]
Tags: #MissingContext
Source:
%%
# Datastore tuples
- [[202203080152 Entity Attribute Value]]
- [[zk/202203080153 Transactional Entity Attribute Value]]
#### What's the context?
I think where I was going with this is that each cell that gets entered into the knowledge graph is a tuple. I'm not sure that still makes sense.
## n-tuple
* Entity
* Does a single string serve to identify this?
* Maybe a "Name": {common name, id}
* Can the ID be a UUID?
* What about documents with a DOI? Does this matter?
* Attribute
* Tempted to make this a string
* What if every attribute is a Name?
```protobuf
message Name {
string id = 1; // e.g. a UUID
string common = 2;
};
message Attribute {
Name name = 1;
Value value = 2;
}
message Transaction {
int64 timestamp = 1;
};
message Fact {
Name entity = 1;
Attribute attribute =2;
Value value = 3;
Transaction transaction = 4;
boolean retraction = 5;
};
```

15
docs/KExocortex/Kortex.md Normal file
View File

@@ -0,0 +1,15 @@
%%
Title: kortex
Created: 2022-03-08 11:34
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# kortex
kortex was an initial attempt at building an [[Resources/Cognition/Exocortex|exocortex]]; it primarily focused on the [[Archive/Computing/KExocortex/KnowledgeGraph|knowledge graph]] and didn't have any notion of an [[Archive/Computing/KExocortex/Elements#The artifact repository|artifact repository]].
- [[Resources/Computing/Lang/Go|Go]] [source code](https://github.com/kisom/kortex)
- [[Resources/Computing/Lang/CPP|C++]] [source code](https://gitlab.com/kisom/kortex)

14
docs/KExocortex/RDD.md Normal file
View File

@@ -0,0 +1,14 @@
%%
Title: RDD
Created: 2022-03-09 00:46
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# RDD
I forgot what this stood for.
I kind of want to stream or record videos of working on the exocortex to make me think more about it.

39
docs/KExocortex/RDD/2022/02/23.md Normal file
View File

@@ -0,0 +1,39 @@
%%
Title: RDD 2022-02-23
Created: 2022-03-09 00:47
Status:
Parent: [[Archive/Computing/KExocortex/RDD]]
Tags:
Source:
%%
# 2022-02-23
## Goal
Build a web server that lets me stash URLs (links and PDFs, primarily) to an
artifact store.
## How do I get there?
### Blobs
- [X] Proto definition for archive blobs
- [X] Database schema for archive blobs
- [X] SQL migration (using [sql-migrate](https://github.com/rubenv/sql-migrate))
- [ ] Go package for archive blobs
- [ ] blob store
- [ ] syncq
- [ ] CLI tool for inserting blobs
### Artifacts
- [ ] What does an artifact look like? Develop the data model.
- [ ] Proto definitions for an archive entry
- [ ] Database schema for archive entries
- [ ] SQL migration
### Web service
- [ ] gRPC service
- [ ] HTTP backend that talks to the gRPC service
- [ ] HTML frontend with authentication
- [ ] (Bonus) CLI tool to interact with the webserver

21
docs/KExocortex/RDD/2022/03/03.md Normal file
View File

@@ -0,0 +1,21 @@
%%
Title: RDD [[daily/2022-03-03]]
Created: 2022-03-09 00:48
Status:
Parent: [[Archive/Computing/KExocortex/RDD]]
Tags:
Source:
%%
# [[daily/2022-03-03]]
- [X] Artifact design doc skeleton
- [X] Write tag and category code
- [X] Blobstore
- [X] Remote store
- [ ] Sync Queue
- [ ] Artifact spec
- [ ] Artifact proto def
- [ ] Artifact gRPC endpoints
- [ ] Artifact SQL schema
- [ ] Basic gRPC API server

175
docs/KExocortex/Spec.md Normal file
View File

@@ -0,0 +1,175 @@
%%
Title: Exocortex functional spec
Created: 2022-03-07 17:08
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# Exocortex functional spec
kExocortex is a tool for capturing and retaining knowledge, making it searchable.
This is the initial top-level draft to sort out the high-level vision.
## Summary
The more you learn, the harder it is to recall specific things. Fortunately, computers are generally pretty good at remembering things. kExocortex is my attempt at building a knowledge graph for long-term memory.
In addition to having functionality like notetaking systems like [Dendron](https://dendron.so), I'd like to keep track of what I call artifacts. An artifact is a source of some knowledge; it might be a PDF copy of a book, an image, or a URL.
In a perfect world, I would have a local copy of everything with a remote backup. The remote backup lets me restore the exocortex in the event of data loss.
## Usage sketches
### Research mode
If I am researching a topic, I have a top-level node that contains all the research I'm working on. I can link artifacts to a note, including URLs. One of the reasons it makes sense to attach a URL to a document is that I can reuse them, as well as go back and search URLs based on tags or categories. It would make sense to tag any artifacts with relevant tags from the note once it is saved.
For example, let's say that I am research graphing databases. In Dendron, this note lives under `comp.database.graph`. I might find this O'Reilly book on [Neo4J](https://go.neo4j.com/rs/710-RRC-335/images/Neo4j_Graph_Algorithms.pdf) that discusses graph algorithms. I might link it here, and I might link it under a Neo4J-specific node. I would store the PDF in an artifact repository, adding relevant tags (such as "graph-database", "neo4j", "oreilly") and categorize it under books, PDFs, comp/database/graph/neo4j. Going forward, if I want to revisit the book, I don't have to find it online again. It's easily accessible from the artifact repository.
The user interface for the knowledge graph should show a list of associated artifacts.
Nodes are also timestamped; I am leaning towards keep track of every time a page was edited (but probably not the edits). If I know I was researching graph databases last week, and I log the URLs I was reading as artifacts, I have a better history of what I was reading.
### Reading from a mobile device
Sometimes I'm on my iPad or phone, and I want to save the link I'm reading. I should be able to stash documents, URLs, etc, in the artifact repository. This implies a remote endpoint that I can enter a URL and a tag, and have that entered into the artifact repository later.
### Cataloging artifacts
If I've entered a bunch of artifacts, I should be able to see a list of ones that need categorizing or that aren't attached to a node.
### Autotagging
The interface should search the text of a note to identify any tags. This brings up an important feature: notes consist of cells, and each cell has a type. The primary use case is to support markdown formatting and code blocks, while not touching the code blocks during autotagging. For example,
````
---
node: today.2022.02.21
---
I figured out how to get Cayley running in production.
\```
cayleyd --some flag --other flag
\```
````
The exocortex would see Cayley, identify that as a node, and add the tags for that node to this one. It might see production and add that as a tag, e.g. for ops-related stuff.
### Fast capture
I should be able to enter a quick note, which would go under a daily node tree. Something like `quick.2022-02-27.1534`.
This would get autotagged. Quick notes might also get a metadata tag indicating whether I went back and integrated them into the rest of the knowledge graph.
One way I could use this might be to text or email a note, or to have a quick capture program on my computer.
## Requirements & Assumptions
What should it do? What assumptions are being made about it? What's considered "in scope" and what won't the project try to do?
Does it need to be compatible with any existing solutions or systems?
If it's a daemon, how are you going to manage it?
What are the dependencies that are assumed to be available?
## System Design
### Major components
The system has two logical components: the artifact repository and the knowledge graph.
#### Artifact repository
There should be, at a minimum, a local artifact repository. It will have its own tooling and UI for interaction, as well as being linked to the knowledge graph.
Previous prototypes stored artifact metadata in SQLite, and the contents of the artifacts in a blob store. The blob store is a content-addressable system for retrieving arbitrary data. A remote option might use an S3-equivalent like Minio.
#### Knowledge graph
The knowledge graph stores nodes. The current model stores the graph in SQLite, using an external file sync (e.g. syncthing) to sync the databases across machines.
### Data model
Previous prototypes used separate SQLite databases for the artifact repository and the knowledge graph.
#### Single SQLite database
The concern with a single SQLite database is that it would be accessed by two different systems, causing potential locking issues.
This could be solved by a single unified backend server; this is the preferred approach.
#### Split SQLite databases
The original prototype split the databases for performance reasons. However, this was based on any empirical evidence.
The major downside to this is that tags and categories are not shared between the artifact repository and the knowledge graph. Categories might make sense for splitting; e.g. an artifact category might be 'PDF' while a node might have the category 'Research'. However, tags should be shared between both systems.
#### PostgreSQL database
Another option is to to use postgres. This brings a heavy ops cost, while enabling a variety of replication and backup strategies.
### Architectural overview
![[assets/images/exo-arch.png]]
There is a backend server, `exod`, that will have a gRPC endpoint for communicating with frontends. The approach allows for a reverse-proxy front end on a public server over Tailscale for remote devices. It also maintains a local blob store, the database, and a connection to a remote minio server for backing up blobs and retrieving missing blobs.
If a standard HTTP API is needed, it can be added in later. One potential use for this is for retrieving blobs (e.g. GET /artifacts/blob/id/...).
## Supportability
### Failure scenarios
#### Data corruption
If the data is corrupted locally, a local import from the remote end would restore it. Alternatively, it may be restored from local backups.
If the data is corrupted remotely, a local export to the remote end would restore it.
### Platform support
The main program would ideally run on Linux primarily, but I'd like to be able to use it on my Windows desktop too.
### Packaging and deployment
## Security
The gRPC endpoint should be authenticated. The system is intended to operate over localhost or a local network, so the use of TLS is probably untenable. [minica](https://github.com/jsha/minica) is an option, but then key rotation needs to be built in.
A possible workaround is to only enable [[Resources/Computing/Security/Authentication|authentication]] (HTTP basic auth will suffice) on the reverse proxy, which will also have TLS.
## Project Dependencies
The software should rely on no external sources, except for the software packages that it uses. This can be mitigated with vendoring.
## Open Issues
- If I track each time a page was edited, does it make sense to roll this up? e.g. I don't track edits to the second, but maybe to the hour or day.
## Milestones
1. Specifications
a. Write up spec for the artifact repository data structures.
b. Write up a spec for the knowledge graph data structures.
2. Core systems
a. Build the artifact repository server.
b. Build the backend for the knowledge graph.
c. Build rough CLI interfaces to both.
3. Build the user interfaces.
a. Simple note taking.
b. Artifact upload and searching by tag, content type, title.
## Review History
This may not be applicable, but it's usually nice to have someone else sanity check this.
Keep a table of who reviewed the doc and when, for in-person reviews. Consider having at least 1 in-person review.

142
docs/KExocortex/Spec/Artifacts.md Normal file
View File

@@ -0,0 +1,142 @@
%%
Title: Artifact data spec
Created: 2022-03-07 17:07
Status:
Parent: [[Archive/Computing/KExocortex/Spec]]
Tags:
Source:
%%
# Artifact data spec
An artifact can be thought of as a source of knowledge. For example, if I am keeping notes on a research paper, the artifact is that paper.
At a minimum, an artifact should have a standard header with metadata. It should store some authorship information (e.g. citation information). An artifact will have snapshots, which indicate current content either at a specific point in time or in a specific format. A website might have snapshots for different times it was scraped; a book might have snapshots for different editions of the book or for different formats (e.g. PDF and EPUB).
## The header
This datatype will be common to all objects, including structures later in the knowledge graph itself. In many cases, such as a blob, the tags will be empty as they will be inherited implicitly through the parent Artifact type.
```go
type Header struct {
ID string
Type ObjectType
Created int64
Modified int64
Categories []string
Tags []string
Meta Metadata
}
```
## Metadata
Metadata is a mapping of keys to values. These values might not be integers; consider the case where we'd want to track filesize or something like that.
Metadata is defined as
```go
type Value struct {
Contents string
Type string
}
type Metadata map[string]Value
```
## Blobs
With these two types defined, we can define a blob. A Blob has a header, a content type, and some data.
```go
type Blob struct {
ID string
Format string // MIME type
Body io.ReadCloser
}
```
## Citations
A citation can be thought of as the bibliographic information for the artifact. Nothing in this should be strictly required. A citation occurs at the artifact level, but it could also occur at the snapshot level. This is like having base information (such as author and publisher) that applies to all of the snapshots, while the snapshot might override attributes like the specific edition.
### Publishers
A starting point is the publisher type.
```go
type Publisher struct {
Header Header
Name string
Address string
}
```
This is simple enough; the publisher really just needs a name and address, and it gets a Header whose Metadata can be used to inject any additional fields.
### Citations defined
Putting some of these pieces together:
```go
type Citation struct {
Header Header
DOI string
Title string
Year int
Published time.Time
Authors []string
Publisher *Publisher
Source string
Abstract string
}
```
We are strictly interested in containing the fields; the presentation layer can handle linking to the DOI, for example.
## Snapshots
So we have the basic pieces in place now to define a snapshot:
```go
type Snapshot struct {
Header Header
ArtifactID string
Stored time.Time
DateTime time.Time
Citation *Citation
Blobs map[MIME]*Blob
}
```
It needs to know the ID of the artifact that it belongs to. We track the time it was stored --- which could be a unix timestamp, but for consistency with the other fields, we'll keep it as a standard time. DateTime is the time used for the snapshot; it can be a built off the year from the citation if needed, or it could be more refined.
One design choice here that could be questioned is the used of the MIME type associated with the blob. The example I can think of here is the [[Resources/Reading/Books/Maths/NoBSGuideToMathAndPhysics|No BS Guide to Math and Physics]], which has a pair of PDFs; one for reading on a tablet, and one for printing. I think that could be solved by using a [[Resources/Computing/MediaTypes|media type]] parameter like "application/pdf; format=screen".
## The artifact type
Combining these together, we have the artifact type itself.
```go
type Artifact struct {
ID string
Type ArtifactType
Latest time.Time // latest snapshot
History map[time.Time]*Snapshot
}
```
The Type is an enumeration that can be added to; a few known types to start with are
* Unknown
* Custom
* Article
* Book
* URL
* Paper
* Video
* Image
If the type is "Custom", the Header should have a metadata entry for "ArtifactType" to custom define it.
The Latest should refer to the most Snapshot.DateTime in its collection of snapshots.
## Timestamps
All timestamps should be suitable for referencing dates prior to epoch 0; they should be encoded in UTC and locally converted. For example, if the client is uploading a new artifact, it should convert its local time to UTC, then send this to the server. We can enforce this in Go using the `Local` timezone, but it's not foolproof.
## Next steps
* Define protobufs.
* Define a SQL schema.

15
docs/KExocortex/Taxonomy.md Normal file
View File

@@ -0,0 +1,15 @@
%%
Title: Note taxonomy
Created: 2022-03-08 00:40
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# Note [[Resources/Languages/English/Vocab/Taxonomy|taxonomy]]
Using Dendron is giving me some ideas for how to enter and display notes. I think that a note should be entered [C2 wiki style](https://wiki.c2.com/); that is, while Dendron names nodes like `kexocortex.taxonomy` or `comp.algorithms.wave-function-collapse`, I'd rather `Taxonomy` with a parent node of `kExorcortex` or `WaveFunctionCollapse` → `Algorithms` → `Comp`. Really, I'd prefer `comp` be replaced with `Computers`.
Another approach is my current [[index|Zettelkasten]] approach, the concept of [[202203062336 Hierarchy vs heterarchy|hierarchy vs heterarchy]].

27
docs/KExocortex/UI.md Normal file
View File

@@ -0,0 +1,27 @@
%%
Title: Exocortex UI
Created: 2022-03-08 03:09
Status:
Parent: [[Archive/Computing/KExocortex]]
Tags:
Source:
%%
# Exocortex UI
A huge part of the exocortex is having a useful user interface, one that allows for querying and whatnot.
### Java
* [Compose](https://www.jetbrains.com/lp/compose/) -- requires gradle, couldn't get it to build.
* [[Resources/Computing/Lang/Java/JavaFX|JavaFX]]
### Go
- [Fyne](https://github.com/fyne-io/fyne) - a cross-platform UI based on Material
### Things to steal
* IntelliJ has the CTRL+SHFT+A to bring up the actions menu. This would be useful to switch modes, enable quickly querying, etc.
* Dendron's C-L is nice for creating notes.