Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/rishvic/notes

An evidence-grounded personal notes framework in AsciiDoc - every note typed by intent (Reference, Internalise, Track), with spaced-repetition practice built in.
https://github.com/rishvic/notes

Last synced: 28 days ago
JSON representation

An evidence-grounded personal notes framework in AsciiDoc - every note typed by intent (Reference, Internalise, Track), with spaced-repetition practice built in.

Awesome Lists containing this project

README 

          
= Personal Notes — Operating Manual

:toc: macro

:toclevels: 3

:icons: font



A personal notes system built on one load-bearing idea: every note has a single

*intent* — *Reference* (look it up on demand), *Internalise* (get it into your

head), or *Track* (work a backlog) — and that intent decides how you write the note,

where it lives, and how you revisit it.



The method is *evidence-tiered, not productivity folklore*: the strong memory

science is applied only where it actually holds (Internalise); the weaker,

practitioner-level choices are labelled as such. It is fast to reference, pleasant

to author in AsciiDoc, and built so an AI agent can maintain the corpus.



Four documents work together:



[cols="1,3"]

|===

| `CONTEXT.md` | The *glossary* — what each term means. Vocabulary only.

| `docs/adr/` | The *decision records* — _why_ the load-bearing choices were made.

| `README.adoc` (this file) | The *operating manual* — _how you_ write and revisit notes.

| `AGENTS.md` | The *agent contract* — _how the agent_ maintains the corpus.

|===



toc::[]



== Core model: three intents



Every note has exactly one *intent*. Intent is the load-bearing idea of the whole

system: it decides how a note is written, where it lives, how it is revisited — and

which evidence applies.



[cols="1,2,2,2",options="header"]

|===

| Intent | For | Success metric | Revisit by

| *Reference* | Looking something up on demand | Findability | Update on use + light agent sweep

| *Internalise* | Getting something into your head | Retention / production | Spaced retrieval practice

| *Track* | An actionable backlog | Staying triaged | Periodic triage

|===



*Capture* is not an intent — it is the transient state of a raw jotting in `inbox/`

before it is _processed_ into a typed note.



[IMPORTANT]

====

The strong memory science — retrieval practice and spacing — governs *Internalise

notes only*. A Reference note is something you deliberately externalised so you

would _not_ have to remember it; drilling it with spaced repetition is a category

error. See `docs/adr/0002-type-notes-by-intent.md`.

====



== Directory layout



[source]

----

notes/

├── CONTEXT.md              glossary

├── README.adoc             this manual

├── AGENTS.md               agent contract

├── docs/adr/               decision records

├── inbox/                  Capture: raw jottings, zero ceremony

├── reference/              look-it-up notes

├── internalise/            production self-test notes

│   └── .srs/               machine-only: log.jsonl + state.json

└── track/                  backlogs grouped by status

----



* *One file per topic.* Split a file only when it stops being scannable at a

  glance, or it grows two-or-more independently-referenced ideas.

* *Filenames are subject slugs* — `lowercase-kebab.adoc`. No dates, no timestamp

  IDs (dates live in metadata and inline, never in filenames).

* *No deep sub-folders.* Subject is carried by the filename and by `xref:` links,

  not by a folder tree.



== The note lifecycle



[source]

----

jot (inbox/, zero ceremony)  ──process──▶  typed note (reference/ internalise/ track/)

                                  │

                                  └─ or discard

----



When something is worth keeping but you have no time, drop it in `inbox/` raw.

_Processing_ — selecting, rephrasing, turning an observation into a production

prompt — happens later, deliberately, not mid-thought.



[NOTE]

*How* you process is deliberately yours to shape — there is no validated intake

procedure to enforce (the evidence governs the _note you produce_, not the path

you take to it). The framework's only hard requirements are the per-intent

templates and the corpus invariants the agent checks — the _Validate_ operation

in `AGENTS.md`.



== Writing notes



=== Reference notes



Optimised for *findability and fast scanning*, not memory.



.Template

[source,asciidoc]

----

= 

:intent: reference

:created: 

:updated: 

:tags: 

:source: 



== 



----



Rules:



* *Title names what it answers* — it is the strongest scent cue.

* *Bottom line up front (BLUF).* The answer first; context after.

* *Hierarchy, one idea per section.* Organised material scans (and recalls) better.

* *Your own words*, not verbatim capture. Selection and transformation are the value.

* *Always record `:source:`* for provenance and verifiability.

* *Exclude only what you would regenerate faster than you would find it here*,

  and that carries no selection, distillation, or provenance value. Curation and

  a tracked `:source:` _are_ the value — keep a note for those even when the raw

  facts are a web search away. ("Lookup-able" is about transformation value to

  you, not about whether the fact exists online — see `CONTEXT.md`.)



[NOTE]

Grooming a Reference note is _not_ studying — it will not imprint the content. If

you want it in your head, make an Internalise note instead.



*Revisit:* update a Reference note when you next use it (just-in-time). A low-cadence

agent hygiene sweep handles dead links, duplicates, and staleness. Notes that rot

quickly may set `:review_by: ` so the sweep surfaces them; evergreen

notes omit it and never nag.



=== Internalise notes



Optimised for *durable retention and production*. An Internalise note is a

*production self-test*, never a summary.



.Template — one collapsible item per prompt

[source,asciidoc]

----

= 

:intent: internalise

:created: 

:updated: 

:tags: 



[#%collapsible]

.

====



====

----



Rules:



* *Prompt → hidden response.* Attempt to _produce_ the response before revealing it.

* *Demand production, not recognition* — practise the operation you actually want

  (transfer-appropriate processing). "Does this look right?" trains the wrong thing.

  For a *phrasing or editing fix specifically*, cue the _situation or meaning_ and

  produce the wording cold; showing the flawed text first trains editing, not the

  live production you want.

* *Cue a determinate, derivable answer.* The prompt must pin the target tightly

  enough that you can reliably _produce_ it and that reasonable alternatives are

  clearly wrong — name the meaning and, for a skill, the operation (e.g. "recover

  the buried verb, name who acts"), but not the words themselves. Too loose and the

  answer is arbitrary and untestable; too tight and you pattern-match instead of

  retrieving. When a skill admits faithful variants, show a worked _exemplar_ and

  grade on whether you applied the operation, not on matching the string.

* *Generate, don't re-read* — the value is in producing the answer yourself.

* *Capture raw first, process later.* Jot the observation in `inbox/`; turn it into a

  prompt when you process it.

* Each item carries a stable `[#item-id]` so the scheduler can track it.



*Revisit:* spaced retrieval practice, run by the agent — see

<>.



=== Track notes



An actionable backlog. Items live under *status* sub-headings.



.Template

[source,asciidoc]

----

= 

:intent: track

:created: 

:updated: 

:tags: 



== Active

* 



== Exploring

* 



== Tabled

* 



== Done

* 

----



*Revisit:* triage periodically (the agent presents the backlog by status and asks

"what changed?"). Promote, demote, and prune.



== Metadata



Two tiers, split by churn and audience: *stable, human-meaningful* attributes live

in the file (below); *volatile, machine-only* state lives in a sidecar the agent

manages (`internalise/.srs/`) — specified in `AGENTS.md`.



=== In-file attributes



[cols="1,1,1,3",options="header"]

|===

| Attribute | Required | Applies to | Meaning

| `:intent:` | recommended | all | reference \| internalise \| track (folder is source of truth; sweep checks agreement)

| `:created:` | yes | all | ISO-8601 creation date

| `:updated:` | yes | all | ISO-8601 last substantive edit

| `:tags:` | optional | all | comma-separated, light secondary axis

| `:source:` | yes | reference | provenance URL or citation

| `:review_by:` | optional | reference | decay horizon; sweep surfaces it when due

|===



== Linking



* Use native `xref:` / `<>` with *descriptive link text* (the label is a

  scent cue) — never "see here".

* Link *sparingly and purposefully* — only where you would actually jump.

* *Never hand-maintain backlinks.* The agent derives them by searching the corpus.

* `:tags:` are a light secondary axis, not a primary structure.



A subject's notes may link *across* intents — e.g. an Internalise English note may

`xref:` a Reference grammar note.



[#internalise-revision]

== Internalise revision: practice



Attempt to produce the response, reveal, then self-grade your attempt. These four

*grades* are the fixed interface between practice and scheduling:



[cols="1,3",options="header"]

|===

| Grade | What it means

| *Again* | couldn't produce it

| *Hard* | produced it, but laboured

| *Good* | clean production

| *Easy* | instant

|===



Grade honestly: reset to *Again* only when you genuinely could not produce it;

*Hard* is the escape valve for "almost". The agent records the grade in the log and

reschedules the item with the active *scheduler* — Leitner by default. Clean recall

pushes the next review further out (days → weeks → months); a real miss brings it

back soon. If an item keeps failing, the agent flags it to be *rewritten*, not

re-drilled — chronic failure usually means a bad prompt.



The schedule itself — the intervals, and how each grade moves an item — is the

scheduler's job: see the interface and the Leitner default in `AGENTS.md`.



== Evidence basis



Tiered honestly. Full reasoning and citations live in the ADRs.



[cols="2,3,1",options="header"]

|===

| Area | Basis | Tier

| Internalise: retrieval practice + spacing | Roediger & Karpicke 2006; Cepeda et al. 2006/2008; Dunlosky et al. 2013; Adesope et al. 2017 | *Strong* (experimental, meta-analytic)

| Internalise: production form | Generation effect (Slamecka & Graf 1978); transfer-appropriate processing (Morris et al. 1977) | Strong

| Reference: scanning + findability | Hierarchy & recall (Bower et al. 1969); information scent (Pirolli & Card 1999); PIM navigation (Bergman et al. 2008/2013) | Moderate

| Granularity / Zettelkasten rejection | No controlled evidence for Zettelkasten; PIM navigation studies | Weak / practitioner

| Track maintenance | GTD; "digital gardening" | None (practitioner convention)

|===



[NOTE]

Note-_making_ is not studying (summarising and highlighting are low-utility study

acts — Dunlosky et al. 2013). Reference notes earn their keep as external storage;

learning happens in Internalise notes, through retrieval practice.



== License



https://reuse.software/[REUSE]-compliant and dual-licensed. The *framework* — the

methodology and everything that teaches it (`README.adoc`, `AGENTS.md`,

`CONTEXT.md`, `docs/`) — is link:LICENSES/Apache-2.0.txt[Apache-2.0]. The *example

notes* (`reference/`, `internalise/`, `track/`, including the `.srs/` data) are

link:LICENSES/CC0-1.0.txt[CC0 1.0], dedicated to the public domain so you can copy

one as a seed with no obligation. Per-file terms are declared in `REUSE.toml` (run

`reuse lint` to verify); the reasoning is in

`docs/adr/0005-split-license-apache-and-cc0.md`.



The example notes are *illustrative samples of the method, not maintained content

to adopt verbatim* — fork the framework and write your own.