{"id":50699594,"url":"https://github.com/rishvic/notes","last_synced_at":"2026-06-09T08:32:46.779Z","repository":{"id":361841257,"uuid":"1254492863","full_name":"rishvic/notes","owner":"rishvic","description":"An evidence-grounded personal notes framework in AsciiDoc - every note typed by intent (Reference, Internalise, Track), with spaced-repetition practice built in.","archived":false,"fork":false,"pushed_at":"2026-06-01T13:13:07.000Z","size":36,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T14:24:56.159Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rishvic.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-30T16:26:41.000Z","updated_at":"2026-06-01T13:15:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rishvic/notes","commit_stats":null,"previous_names":["rishvic/notes"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rishvic/notes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishvic%2Fnotes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishvic%2Fnotes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishvic%2Fnotes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishvic%2Fnotes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rishvic","download_url":"https://codeload.github.com/rishvic/notes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishvic%2Fnotes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34098932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T08:32:46.640Z","updated_at":"2026-06-09T08:32:46.758Z","avatar_url":"https://github.com/rishvic.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"= Personal Notes — Operating Manual\n:toc: macro\n:toclevels: 3\n:icons: font\n\nA personal notes system built on one load-bearing idea: every note has a single\n*intent* — *Reference* (look it up on demand), *Internalise* (get it into your\nhead), or *Track* (work a backlog) — and that intent decides how you write the note,\nwhere it lives, and how you revisit it.\n\nThe method is *evidence-tiered, not productivity folklore*: the strong memory\nscience is applied only where it actually holds (Internalise); the weaker,\npractitioner-level choices are labelled as such. It is fast to reference, pleasant\nto author in AsciiDoc, and built so an AI agent can maintain the corpus.\n\nFour documents work together:\n\n[cols=\"1,3\"]\n|===\n| `CONTEXT.md` | The *glossary* — what each term means. Vocabulary only.\n| `docs/adr/` | The *decision records* — _why_ the load-bearing choices were made.\n| `README.adoc` (this file) | The *operating manual* — _how you_ write and revisit notes.\n| `AGENTS.md` | The *agent contract* — _how the agent_ maintains the corpus.\n|===\n\ntoc::[]\n\n== Core model: three intents\n\nEvery note has exactly one *intent*. Intent is the load-bearing idea of the whole\nsystem: it decides how a note is written, where it lives, how it is revisited — and\nwhich evidence applies.\n\n[cols=\"1,2,2,2\",options=\"header\"]\n|===\n| Intent | For | Success metric | Revisit by\n| *Reference* | Looking something up on demand | Findability | Update on use + light agent sweep\n| *Internalise* | Getting something into your head | Retention / production | Spaced retrieval practice\n| *Track* | An actionable backlog | Staying triaged | Periodic triage\n|===\n\n*Capture* is not an intent — it is the transient state of a raw jotting in `inbox/`\nbefore it is _processed_ into a typed note.\n\n[IMPORTANT]\n====\nThe strong memory science — retrieval practice and spacing — governs *Internalise\nnotes only*. A Reference note is something you deliberately externalised so you\nwould _not_ have to remember it; drilling it with spaced repetition is a category\nerror. See `docs/adr/0002-type-notes-by-intent.md`.\n====\n\n== Directory layout\n\n[source]\n----\nnotes/\n├── CONTEXT.md              glossary\n├── README.adoc             this manual\n├── AGENTS.md               agent contract\n├── docs/adr/               decision records\n├── inbox/                  Capture: raw jottings, zero ceremony\n├── reference/              look-it-up notes\n├── internalise/            production self-test notes\n│   └── .srs/               machine-only: log.jsonl + state.json\n└── track/                  backlogs grouped by status\n----\n\n* *One file per topic.* Split a file only when it stops being scannable at a\n  glance, or it grows two-or-more independently-referenced ideas.\n* *Filenames are subject slugs* — `lowercase-kebab.adoc`. No dates, no timestamp\n  IDs (dates live in metadata and inline, never in filenames).\n* *No deep sub-folders.* Subject is carried by the filename and by `xref:` links,\n  not by a folder tree.\n\n== The note lifecycle\n\n[source]\n----\njot (inbox/, zero ceremony)  ──process──▶  typed note (reference/ internalise/ track/)\n                                  │\n                                  └─ or discard\n----\n\nWhen something is worth keeping but you have no time, drop it in `inbox/` raw.\n_Processing_ — selecting, rephrasing, turning an observation into a production\nprompt — happens later, deliberately, not mid-thought.\n\n[NOTE]\n*How* you process is deliberately yours to shape — there is no validated intake\nprocedure to enforce (the evidence governs the _note you produce_, not the path\nyou take to it). The framework's only hard requirements are the per-intent\ntemplates and the corpus invariants the agent checks — the _Validate_ operation\nin `AGENTS.md`.\n\n== Writing notes\n\n=== Reference notes\n\nOptimised for *findability and fast scanning*, not memory.\n\n.Template\n[source,asciidoc]\n----\n= \u003cTitle: name what the note answers\u003e\n:intent: reference\n:created: \u003cYYYY-MM-DD\u003e\n:updated: \u003cYYYY-MM-DD\u003e\n:tags: \u003ccomma, separated\u003e\n:source: \u003curl-or-citation\u003e\n\n\u003cBLUF: the answer, in the first line or two.\u003e\n\n== \u003cSection — one idea\u003e\n\u003cDetail, in your own words.\u003e\n----\n\nRules:\n\n* *Title names what it answers* — it is the strongest scent cue.\n* *Bottom line up front (BLUF).* The answer first; context after.\n* *Hierarchy, one idea per section.* Organised material scans (and recalls) better.\n* *Your own words*, not verbatim capture. Selection and transformation are the value.\n* *Always record `:source:`* for provenance and verifiability.\n* *Exclude only what you would regenerate faster than you would find it here*,\n  and that carries no selection, distillation, or provenance value. Curation and\n  a tracked `:source:` _are_ the value — keep a note for those even when the raw\n  facts are a web search away. (\"Lookup-able\" is about transformation value to\n  you, not about whether the fact exists online — see `CONTEXT.md`.)\n\n[NOTE]\nGrooming a Reference note is _not_ studying — it will not imprint the content. If\nyou want it in your head, make an Internalise note instead.\n\n*Revisit:* update a Reference note when you next use it (just-in-time). A low-cadence\nagent hygiene sweep handles dead links, duplicates, and staleness. Notes that rot\nquickly may set `:review_by: \u003cYYYY-MM-DD\u003e` so the sweep surfaces them; evergreen\nnotes omit it and never nag.\n\n=== Internalise notes\n\nOptimised for *durable retention and production*. An Internalise note is a\n*production self-test*, never a summary.\n\n.Template — one collapsible item per prompt\n[source,asciidoc]\n----\n= \u003cTitle: the subject\u003e\n:intent: internalise\n:created: \u003cYYYY-MM-DD\u003e\n:updated: \u003cYYYY-MM-DD\u003e\n:tags: \u003ccomma, separated\u003e\n\n[#\u003citem-id\u003e%collapsible]\n.\u003cPrompt: the situation/meaning that should make you produce the target\u003e\n====\n\u003cResponse: the form you want to produce — a single canonical answer, or a\nworked exemplar for a skill item — hidden until you expand.\u003e\n====\n----\n\nRules:\n\n* *Prompt → hidden response.* Attempt to _produce_ the response before revealing it.\n* *Demand production, not recognition* — practise the operation you actually want\n  (transfer-appropriate processing). \"Does this look right?\" trains the wrong thing.\n  For a *phrasing or editing fix specifically*, cue the _situation or meaning_ and\n  produce the wording cold; showing the flawed text first trains editing, not the\n  live production you want.\n* *Cue a determinate, derivable answer.* The prompt must pin the target tightly\n  enough that you can reliably _produce_ it and that reasonable alternatives are\n  clearly wrong — name the meaning and, for a skill, the operation (e.g. \"recover\n  the buried verb, name who acts\"), but not the words themselves. Too loose and the\n  answer is arbitrary and untestable; too tight and you pattern-match instead of\n  retrieving. When a skill admits faithful variants, show a worked _exemplar_ and\n  grade on whether you applied the operation, not on matching the string.\n* *Generate, don't re-read* — the value is in producing the answer yourself.\n* *Capture raw first, process later.* Jot the observation in `inbox/`; turn it into a\n  prompt when you process it.\n* Each item carries a stable `[#item-id]` so the scheduler can track it.\n\n*Revisit:* spaced retrieval practice, run by the agent — see\n\u003c\u003cinternalise-revision\u003e\u003e.\n\n=== Track notes\n\nAn actionable backlog. Items live under *status* sub-headings.\n\n.Template\n[source,asciidoc]\n----\n= \u003cTitle: the backlog\u003e\n:intent: track\n:created: \u003cYYYY-MM-DD\u003e\n:updated: \u003cYYYY-MM-DD\u003e\n:tags: \u003ccomma, separated\u003e\n\n== Active\n* \u003citem you are working on now\u003e\n\n== Exploring\n* \u003citem under consideration\u003e\n\n== Tabled\n* \u003citem parked for later\u003e\n\n== Done\n* \u003ccompleted/dropped item\u003e\n----\n\n*Revisit:* triage periodically (the agent presents the backlog by status and asks\n\"what changed?\"). Promote, demote, and prune.\n\n== Metadata\n\nTwo tiers, split by churn and audience: *stable, human-meaningful* attributes live\nin the file (below); *volatile, machine-only* state lives in a sidecar the agent\nmanages (`internalise/.srs/`) — specified in `AGENTS.md`.\n\n=== In-file attributes\n\n[cols=\"1,1,1,3\",options=\"header\"]\n|===\n| Attribute | Required | Applies to | Meaning\n| `:intent:` | recommended | all | reference \\| internalise \\| track (folder is source of truth; sweep checks agreement)\n| `:created:` | yes | all | ISO-8601 creation date\n| `:updated:` | yes | all | ISO-8601 last substantive edit\n| `:tags:` | optional | all | comma-separated, light secondary axis\n| `:source:` | yes | reference | provenance URL or citation\n| `:review_by:` | optional | reference | decay horizon; sweep surfaces it when due\n|===\n\n== Linking\n\n* Use native `xref:` / `\u003c\u003canchor\u003e\u003e` with *descriptive link text* (the label is a\n  scent cue) — never \"see here\".\n* Link *sparingly and purposefully* — only where you would actually jump.\n* *Never hand-maintain backlinks.* The agent derives them by searching the corpus.\n* `:tags:` are a light secondary axis, not a primary structure.\n\nA subject's notes may link *across* intents — e.g. an Internalise English note may\n`xref:` a Reference grammar note.\n\n[#internalise-revision]\n== Internalise revision: practice\n\nAttempt to produce the response, reveal, then self-grade your attempt. These four\n*grades* are the fixed interface between practice and scheduling:\n\n[cols=\"1,3\",options=\"header\"]\n|===\n| Grade | What it means\n| *Again* | couldn't produce it\n| *Hard* | produced it, but laboured\n| *Good* | clean production\n| *Easy* | instant\n|===\n\nGrade honestly: reset to *Again* only when you genuinely could not produce it;\n*Hard* is the escape valve for \"almost\". The agent records the grade in the log and\nreschedules the item with the active *scheduler* — Leitner by default. Clean recall\npushes the next review further out (days → weeks → months); a real miss brings it\nback soon. If an item keeps failing, the agent flags it to be *rewritten*, not\nre-drilled — chronic failure usually means a bad prompt.\n\nThe schedule itself — the intervals, and how each grade moves an item — is the\nscheduler's job: see the interface and the Leitner default in `AGENTS.md`.\n\n== Evidence basis\n\nTiered honestly. Full reasoning and citations live in the ADRs.\n\n[cols=\"2,3,1\",options=\"header\"]\n|===\n| Area | Basis | Tier\n| Internalise: retrieval practice + spacing | Roediger \u0026 Karpicke 2006; Cepeda et al. 2006/2008; Dunlosky et al. 2013; Adesope et al. 2017 | *Strong* (experimental, meta-analytic)\n| Internalise: production form | Generation effect (Slamecka \u0026 Graf 1978); transfer-appropriate processing (Morris et al. 1977) | Strong\n| Reference: scanning + findability | Hierarchy \u0026 recall (Bower et al. 1969); information scent (Pirolli \u0026 Card 1999); PIM navigation (Bergman et al. 2008/2013) | Moderate\n| Granularity / Zettelkasten rejection | No controlled evidence for Zettelkasten; PIM navigation studies | Weak / practitioner\n| Track maintenance | GTD; \"digital gardening\" | None (practitioner convention)\n|===\n\n[NOTE]\nNote-_making_ is not studying (summarising and highlighting are low-utility study\nacts — Dunlosky et al. 2013). Reference notes earn their keep as external storage;\nlearning happens in Internalise notes, through retrieval practice.\n\n== License\n\nhttps://reuse.software/[REUSE]-compliant and dual-licensed. The *framework* — the\nmethodology and everything that teaches it (`README.adoc`, `AGENTS.md`,\n`CONTEXT.md`, `docs/`) — is link:LICENSES/Apache-2.0.txt[Apache-2.0]. The *example\nnotes* (`reference/`, `internalise/`, `track/`, including the `.srs/` data) are\nlink:LICENSES/CC0-1.0.txt[CC0 1.0], dedicated to the public domain so you can copy\none as a seed with no obligation. Per-file terms are declared in `REUSE.toml` (run\n`reuse lint` to verify); the reasoning is in\n`docs/adr/0005-split-license-apache-and-cc0.md`.\n\nThe example notes are *illustrative samples of the method, not maintained content\nto adopt verbatim* — fork the framework and write your own.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frishvic%2Fnotes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frishvic%2Fnotes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frishvic%2Fnotes/lists"}