limitedrush
Back to all writing
Project Log

MemoryRush: A Local AI Project for Reading Memory

GitHub

MemoryRush is a local AI/ML project that turns long-form reading material into source-grounded memory units, core ideas, and recall questions.

Project Overview

MemoryRush is a local AI/ML project built around reading memory. It is not a normal document chatbot, and it is not only a summarizer. The central question is: after reading an article, which ideas are actually worth remembering?

The project turns long-form reading material into a structure that is reviewable, source-grounded, and inspectable:

article
-> stable source paragraphs
-> core ideas
-> memory units
-> source evidence
-> recall questions
-> evaluable processing artifact

The memory units are not detached notes. Each one should point back to concrete source paragraphs, so later review keeps both the compressed idea and the evidence behind it.

Why This Project Exists

Reading often leaves behind a vague impression: something felt useful at the time, but the exact idea fades later. Summaries help with quick review, but they do not always identify what should become long-term memory, and they do not always preserve clear source evidence.

MemoryRush explores a different approach: using AI to extract a small set of high-value memory units from an article, while keeping each unit linked to the original text. It is closer to a post-reading memory organizer than a temporary question-answering tool.

That makes the project useful as a learning experiment as well. The output is not just a fluent paragraph. It is a structured artifact that can be questioned: which source paragraph supports this idea, is this unit duplicated, and can this recall question actually map back to a memory unit?

Input and Output

MemoryRush currently focuses on .txt, .md, and .markdown reading materials. The input can be an article, course note, paper excerpt, or another long-form text. The system first parses the document into stable paragraphs, then passes those paragraphs into the generation and validation flow.

The intended output contains several parts:

  • summary: a compact description of the whole article.
  • core_ideas: a small set of key ideas, each with rationale and evidence.
  • memory_units: reviewable units with type, tags, confidence, and evidence paragraphs.
  • recall_questions: questions for later active recall.
  • validation_report: checks for source references, empty content, duplicated units, and invalid indexes.

The goal is not to produce as much content as possible. The goal is to keep the structure clear. If a memory unit cannot point back to the source, or a recall question references no valid memory unit, it should not be treated as a reliable result.

Source-Grounded Memory Unit

The core concept is a source-grounded memory unit: a compact memory object that remains attached to evidence.

An ideal memory unit includes:

  • concise content,
  • memory_type, such as concept, claim, mechanism, or example,
  • supporting evidence_paragraph_ids,
  • organizing tags,
  • a confidence score,
  • recall questions that can refer back to it.

Instead of only saying "this article is about reading memory," the system should produce a reviewable memory statement and show which paragraphs support it. It keeps "what did I learn" and "why can I trust that extraction" inside the same object.

Document Parsing

The project first parses reading material into SourceDocument and SourceParagraph. Each paragraph has a stable paragraph_id, such as p_001 or p_002. The document itself receives a document_id generated from the file path and text content.

This step looks simple, but it is the foundation for reliable evidence links. MemoryRush:

  • normalizes Windows, Unix, and older newline styles,
  • extracts the title from a Markdown heading or file name,
  • removes the leading Markdown title so it is not duplicated as a body paragraph,
  • splits paragraphs on blank lines,
  • folds internal line breaks into continuous paragraph text,
  • assigns stable paragraph IDs in document order.

In other words, the system does not start by asking the model what the article says. It first builds a stable source-reference system. Without stable paragraph IDs, citation, evaluation, and recall-question mapping all become fragile.

Pipeline Mechanism

MemoryRush can be understood as a small article-memory pipeline:

parse_document()
-> SourceDocument
-> build_prompt_context()
-> MemoryExtractionProvider.generate()
-> ArticleMemoryOutput
-> validate_article_memory_output()
-> ProcessingArtifact

build_prompt_context() formats the document ID, title, and every paragraph_id: text pair into model context. That gives the model explicit IDs to cite instead of vague location descriptions.

Generation is abstracted through the MemoryExtractionProvider protocol. As long as a provider accepts prompt context and returns an ArticleMemoryOutput, the pipeline does not need to care whether the provider is deterministic for local checks or backed by a local model.

The final result is a ProcessingArtifact. It stores the document ID, prompt version, model name, structured output, raw output, and validation report. A run is therefore not just "some generated text"; it becomes an experiment record that can be reproduced, inspected, and compared.

Algorithms and Validation

The most important algorithmic part of MemoryRush is not a complex model architecture. It is the evidence-centered structure and the consistency checks around it.

In the output contract, CoreIdea contains idea, why_it_matters, EvidenceSpan, and salience_score. EvidenceSpan must include a paragraph_id and an exact source quote. MemoryUnit must include content, type, evidence paragraph IDs, tags, and confidence.

The validator checks several failure modes:

  • whether a core idea references a paragraph ID that exists,
  • whether the quoted evidence appears in the referenced paragraph,
  • whether a memory unit is empty,
  • whether a memory unit duplicates an earlier unit,
  • whether every memory unit references at least one evidence paragraph,
  • whether each recall question points to an existing memory unit index.

These checks shift the project from "does the model sound smart" to "can the model output be constrained by evidence." That is one of the most important differences between MemoryRush and a generic summarizer.

Technologies Used

The project intentionally stays lightweight. It relies on Python and a small set of clear engineering contracts instead of starting with a heavy framework.

  • Python dataclasses define the domain objects and structured output contracts.
  • pathlib handles cross-platform paths.
  • hashlib.sha1 creates stable document IDs.
  • re handles Markdown title detection, paragraph splitting, and newline normalization.
  • json serializes processing artifacts and parses provider output.
  • urllib.request connects to the local Ollama /api/generate endpoint.
  • argparse provides a command-line processing entry.
  • Streamlit is used for the local interactive-app direction.
  • Ollama / qwen2.5:7b-instruct can be used for local model experiments.

This stack matches the project identity: MemoryRush is a local research prototype, not a SaaS product, browser extension, or commercial reading app. The code favors readability, reproducibility, and source-grounded structure.

Difference From RAG

Traditional RAG is usually:

user question
-> retrieve related chunks
-> generate answer

MemoryRush is closer to:

user reads an article
-> extract memorable ideas
-> attach source evidence
-> generate recall questions
-> support later recall and retrieval

It is less about finding an answer at question time, and more about deciding what memory structure should remain after reading. RAG usually begins when a user asks a question; MemoryRush begins after a reading session and creates a stable memory surface for future recall.

Local First

MemoryRush is designed as a local-first project because reading material may include private notes, course content, paper excerpts, or unfinished ideas. Keeping the workflow local reduces privacy risk and makes research experiments easier to reproduce.

Local models can be connected through Ollama. The point is not to chase the largest model first, but to keep the pipeline clear, the output structured, and the evidence links inspectable. For this project, a smaller but controllable local workflow is often more useful than a stronger remote black box during early experimentation.

What Makes It Interesting

The interesting part of MemoryRush is that it turns "AI summarizes this for me" into a more precise question: can AI help decide what deserves to become memory?

That question forces the system to connect three layers:

  • what the source article says,
  • which ideas are worth keeping,
  • how those ideas can be recalled later.

So it is not only an NLP demo and not quite a traditional knowledge-base tool. It is a small experimental system connecting reading, evidence, memory, and review.