From 784763ba82c87cc29e2f13c38e5b180772861a48 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 22 Jun 2026 20:28:15 +0000 Subject: [PATCH 1/3] docs: add Design Philosophy ("imperfection by design") MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds docs/PHILOSOPHY.md โ€” a standalone writeup of why CogniFold deliberately models memory as situated, lossy and biased rather than chasing a perfect, unbiased ground-truth recall store. Bias is framed as the mechanism that makes proactivity possible, not a defect. Covers four cognitive realities modeled on purpose โ€” situated cognition, confirmation bias / reasoning inertia, locality of working memory, and metacognitive blind spots (unknown unknowns) โ€” maps each to a concrete mechanism (intent-conditioned retrieval, decay/completion rewrites, hierarchical context window, intent crystallization), and explains the evaluation stance: report the proactive-substrate stack, not inflatable per-benchmark ceilings that reward auto-loop hallucination. Also adds a condensed Design Philosophy section + nav/TOC links in the README. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01HCToJStvPhZbWGY2ZcBfy7 --- README.md | 16 +++- docs/PHILOSOPHY.md | 191 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+), 1 deletion(-) create mode 100644 docs/PHILOSOPHY.md diff --git a/README.md b/README.md index 5ed2f4f..5b6b387 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@
-๐ŸŒ Live Demo  ยท  ๐Ÿ—๏ธ Architecture  ยท  ๐Ÿš€ Deploy  ยท  ๐Ÿ”Œ Integrations  ยท  โœ๏ธ Prompt Profiles  ยท  ๐Ÿงญ North Star +๐ŸŒ Live Demo  ยท  ๐Ÿ—๏ธ Architecture  ยท  ๐Ÿš€ Deploy  ยท  ๐Ÿ”Œ Integrations  ยท  โœ๏ธ Prompt Profiles  ยท  ๐Ÿงญ Philosophy  ยท  ๐Ÿงญ North Star
@@ -35,6 +35,7 @@ ## ๐Ÿ“– Table of Contents - [๐ŸŽฏ Highlights](#-highlights) +- [๐Ÿงญ Design Philosophy: imperfection by design](#-design-philosophy-imperfection-by-design) - [๐Ÿง  Concepts in 60 seconds](#-concepts-in-60-seconds) - [๐ŸŽฌ Demo](#-demo) - [๐Ÿ› ๏ธ Installation](#๏ธ-installation) @@ -56,6 +57,19 @@ 3. **๐ŸŒฑ Conceptual Bootstrapping.** Accumulation, compression, decay, completion โ€” four structural debts of a streaming event log, resolved as transparent graph rewrites: test-time learning without gradient updates or surface text rewriting. 4. **๐Ÿ“Š Evaluation.** CogEval-Bench isolates proactive emergence from retrieval accuracy; seven downstream benchmarks confirm the substrate stays robust on conventional memory tasks. +## ๐Ÿงญ Design Philosophy: imperfection by design + +CogniFold does **not** chase a perfect, omniscient, unbiased recall store. It models memory the way cognition actually works โ€” *situated, lossy, and opinionated* โ€” because that is precisely what makes proactivity possible. A system that stored everything with equal weight and perfect fidelity would be a database: faithful, and completely reactive. What lets memory *act ahead of you* is the same thing that makes it imperfect โ€” it decides what matters, what fades, and what crystallizes into an intent. **The bias is not a defect we are slowly engineering away. The bias is the mechanism.** We optimize for useful proactive structure, not for maximal ground-truth fidelity. + +Four cognitive realities we model **on purpose** instead of designing around: + +1. **Situated cognition.** Cognition is embedded in the active context, goals, and history; the deeper into a problem, the more the frame gets *locked*. Retrieval is conditioned on the active intent and recent trace, so the graph reasons *from where it already is*. +2. **Confirmation bias / reasoning inertia.** Once an understanding forms, contradicting signals get filtered and the view is reinforced โ€” agents inherit this through the reasoning path accumulated in a context window. We bound that inertia structurally (decay, completion, re-linking) instead of pretending each turn is a clean slate. +3. **Locality of working memory.** Human working memory activates only the currently relevant nodes; an LLM's attention weights decide *what is even seen*. We embrace locality โ€” the hierarchical context window surfaces a focused, partial view rather than dumping the whole graph. +4. **Metacognitive blind spots (unknown unknowns).** The most dangerous gap is the part you don't know you don't know โ€” you can't feel you need help. A *proactive* substrate matters here: intents that crystallize from topology can surface what you never thought to ask, partially covering the blind spot pure on-demand retrieval can't reach. + +This is also why our reported benchmark numbers are the **proactive-substrate stack, not per-benchmark tuned ceilings**. Several older tasks are trivially inflatable with a task-specialized reader โ€” but that path rewards *auto-loop hallucination*, the reader confabulating to satisfy a metric instead of reading memory. That's exactly the metacognitive failure above, so we don't optimize for it. **The flaw is the point.** โ†’ Full writeup: [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md). + ## ๐Ÿง  Concepts in 60 seconds CogniFold ingests an asynchronous event stream and folds it into a typed concept graph. Four node types โ€” the first three mirror Complementary Learning Systems (CLS) theory: diff --git a/docs/PHILOSOPHY.md b/docs/PHILOSOPHY.md new file mode 100644 index 0000000..adae0dd --- /dev/null +++ b/docs/PHILOSOPHY.md @@ -0,0 +1,191 @@ +# Design Philosophy: Imperfection by Design + +> **This document is an extension of `CLAUDE.md` and the [README](../README.md). Read those first for the system overview.** + +CogniFold does **not** chase a perfect, omniscient, unbiased recall store. It models +memory the way cognition actually works โ€” *situated, lossy, and opinionated* โ€” because +that is precisely what makes proactivity possible. + +This page explains why the biases below are deliberate design commitments rather than +defects we are slowly engineering away, and how each one maps to a concrete mechanism in +the system. + +--- + +## The thesis + +A memory that stored everything, weighted everything equally, and recalled it with +perfect fidelity would be a **database**. It would be faithful โ€” and completely +**reactive**. It can only answer what you explicitly ask, in the framing you happen to +ask it. + +What lets memory *act ahead of you* โ€” surface a deadline you forgot, connect two +conversations you never linked, raise an intent you didn't think to query โ€” is the same +machinery that makes it imperfect. To be proactive, a memory must **decide**: what +matters, what fades, what gets reinforced, and what crystallizes into an intent. Every +one of those decisions is a bias. **The bias is not a bug on the way to a perfect memory. +The bias is the mechanism.** + +So CogniFold optimizes for **useful proactive structure**, not for maximal ground-truth +fidelity. The flaw is the point. + +--- + +## Why "a faithful memory" is the wrong target + +The dominant framing for agent memory is *retrieval accuracy*: store text, embed it, +fetch the nearest neighbors, measure how often the right chunk came back. Under that +framing, every departure from verbatim recall is an error to be minimized, and the ideal +system is a lossless index. + +But human memory is not a lossless index, and it is not trying to be. It is **generative +and reconstructive** โ€” it abstracts, forgets, distorts, and completes. Those are not +failures of the system; they are how it stays small, fast, and *forward-looking* enough to +be useful in an open-ended world. CogniFold takes the same position: the interesting +target is not "did we keep every token," but "did the structure that emerged let the +system act on the user's behalf." + +This reframes what counts as a good memory and, consequently, what counts as a good +benchmark (see [What this means for evaluation](#what-this-means-for-evaluation)). + +--- + +## Four cognitive realities we model on purpose + +Each of the following is a well-studied feature of biological cognition that *also* shows +up in LLM-based agents. Rather than design around them, CogniFold embodies them. + +### 1. Situated cognition + +**The phenomenon.** Cognition is never isolated. It is embedded in the current context, +the active goal, and the history that led here. The deeper you go into a problem, the more +your frame gets *locked* by that situation โ€” and the harder it is to step outside it. + +**The agent analogue.** A reasoning agent reads from where it already is: the active task +and recent trace condition everything that follows. There is no "view from nowhere." + +**CogniFold's stance.** We make situatedness explicit rather than pretending to a neutral +global read. Retrieval is conditioned on the **active intent** and recent episodic trace, +so the graph reasons *from its current standpoint*. This is a feature: a proactive system +must be anchored in a situation to know what to push. + +**Mechanism.** Intent-conditioned retrieval; the hierarchical context window's +`immediate / working / background` bands; edge-type weighting routed by query intent +(`symbolic/intent_router`). + +### 2. Confirmation bias / reasoning inertia + +**The phenomenon.** Once an understanding forms in a particular direction, contradicting +signals get filtered out and the existing interpretation is reinforced. Belief has +momentum. + +**The agent analogue.** The reasoning path accumulated in a context window builds +inertia โ€” each step is anchored by the steps before it, so an early commitment propagates +forward whether or not it was right. + +**CogniFold's stance.** We treat this inertia as **real and structural**, not something a +"fresh" prompt erases. Instead of pretending each turn is a clean slate, we bound and +correct accumulated belief through explicit graph rewrites over time. + +**Mechanism.** The four structural debts of a streaming log โ€” **accumulation, compression, +decay, completion** โ€” resolved as transparent, auditable graph rewrites (test-time +learning, no gradient updates, no surface-text rewriting). Decay and re-linking are how an +over-reinforced path loses its grip. + +### 3. Locality of working memory + +**The phenomenon.** Human working memory is finite. Only the currently relevant knowledge +nodes are activated at once; other perspectives are suppressed. You cannot hold the whole +of what you know in view simultaneously. + +**The agent analogue.** An LLM's attention is similar: the weight distribution over the +current tokens decides *what is even seen*. Context is finite and the salience profile is +narrow by construction. + +**CogniFold's stance.** We embrace locality as a **feature**, not a limit to paper over by +stuffing the window. The system deliberately surfaces a focused, partial view rather than +dumping the whole graph โ€” because a partial-but-relevant view is what enables fast, +situated action. + +**Mechanism.** The `HierarchicalContextSelector` and its bounded bands; scored, capped +context assembly instead of full-graph serialization. + +### 4. Metacognitive blind spots (unknown unknowns) + +**The phenomenon.** The most dangerous gap is the part you don't know you don't know. You +can't feel its absence, so you never think to ask โ€” and therefore can't be helped by any +system that only answers questions. + +**The agent analogue.** A purely on-demand (query โ†’ retrieve โ†’ answer) memory is +structurally incapable of covering this gap: it can only return what you knew enough to +ask for. + +**CogniFold's stance.** This is the deepest reason the substrate is **proactive**. Intents +that crystallize from graph *topology* โ€” from conditions accumulating whether or not you +noticed โ€” can surface something you never thought to query. That is partial coverage of a +blind spot that on-demand retrieval can never reach. + +**Mechanism.** Intent crystallization: when a concept cluster crosses a density threshold, +an `intent` node forms and is surfaced through the proactive context window with no query +asked. Prospective memory as a property of the topology, not the agent's policy. + +--- + +## What this means for the architecture + +The philosophy is not decoration โ€” it is why the tri-layer substrate looks the way it +does: + +| Cognitive commitment | Mechanism in CogniFold | +|---|---| +| Situated cognition | Intent-conditioned retrieval; intent-routed edge weights; context bands | +| Reasoning inertia is real | Accumulation / compression / **decay** / completion as graph rewrites | +| Locality is a feature | Hierarchical, bounded context window (not full-graph dumps) | +| Cover unknown unknowns | **Intent crystallization** from topology โ†’ proactive surfacing | + +A memory that refused these biases could not crystallize an intent, could not forget a +stale one, and could not decide what to surface unprompted. It would be inert. + +--- + +## What this means for evaluation + +If imperfection is the design, then **the highest score on a recall-style benchmark is not +the goal**, and chasing it can actively harm the system. + +- We report the **proactive-substrate stack** โ€” the configuration that keeps intent + generation working end-to-end โ€” **not a per-benchmark tuned ceiling.** +- Several older benchmarks (ToMi in particular) are **trivially inflatable** with a + task-specialized reader. But that path rewards **auto-loop hallucination**: the reader + confabulates an answer that satisfies the metric instead of reading from memory. That is + precisely the *metacognitive blind spot* failure above โ€” the model not knowing that it + doesn't know, and filling the gap with a fabrication. +- Optimizing for those points would trade the system's purpose for a leaderboard number. + So we don't. We'd rather publish an honest number from the substrate we actually ship. + +This is also why **CogEval-Bench** exists: it isolates *proactive emergence* (Purity, +Proactivity, Compression) from retrieval accuracy, measuring the thing the philosophy +actually commits to. See [BENCHMARK.md](BENCHMARK.md) for the full results and protocol. + +--- + +## What we explicitly reject + +- **"Perfect recall is the goal."** No โ€” perfect recall is a reactive database. Proactivity + requires deciding, and deciding is biasing. +- **"Bias is a defect to minimize to zero."** No โ€” bias is the selection pressure that makes + structure (and intent) emerge. +- **"A bigger context window solves locality."** No โ€” locality is a feature; relevance beats + volume. +- **"Higher benchmark number = better memory."** No โ€” not when the number comes from a + configuration we don't ship and that encourages confabulation. + +--- + +## Closing + +CogniFold is a bet that the path to genuinely helpful, *proactive* memory runs through +modeling cognition honestly โ€” biases included โ€” rather than approximating an omniscient +oracle. We don't pursue a perfect ground truth. We pursue a substrate that is situated, +forgets on purpose, sees locally, and occasionally tells you something you didn't know to +ask. **The flaw is the point.** From 86f68622b7efe05977eeb3e99080eef19f2789d5 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 22 Jun 2026 20:31:33 +0000 Subject: [PATCH 2/3] docs(readme): rename "Live Demo" -> "Live progress track" Per review feedback on PR #30 (duanyiqun): the site is a live progress tracker, not a demo. Updates the header badge and the nav link. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01HCToJStvPhZbWGY2ZcBfy7 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5b6b387..4e64ac1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@

CogniFold: Always-On Proactive Memory
via Cognitive Folding

-Live Demo +Live progress track Brain Memory Coverage Paper CogEval-Bench Dataset @@ -20,7 +20,7 @@
-๐ŸŒ Live Demo  ยท  ๐Ÿ—๏ธ Architecture  ยท  ๐Ÿš€ Deploy  ยท  ๐Ÿ”Œ Integrations  ยท  โœ๏ธ Prompt Profiles  ยท  ๐Ÿงญ Philosophy  ยท  ๐Ÿงญ North Star +๐ŸŒ Live progress track  ยท  ๐Ÿ—๏ธ Architecture  ยท  ๐Ÿš€ Deploy  ยท  ๐Ÿ”Œ Integrations  ยท  โœ๏ธ Prompt Profiles  ยท  ๐Ÿงญ Philosophy  ยท  ๐Ÿงญ North Star
From 570614ab59e56c055d9a94e06034d73c388c6c5b Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 22 Jun 2026 20:33:15 +0000 Subject: [PATCH 3/3] docs(readme): move Design Philosophy to the top Per review feedback on PR #30 (duanyiqun): Philosophy first in the table of contents and as the first content section, ahead of Highlights. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01HCToJStvPhZbWGY2ZcBfy7 --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 4e64ac1..4b65db6 100644 --- a/README.md +++ b/README.md @@ -34,8 +34,8 @@ ## ๐Ÿ“– Table of Contents -- [๐ŸŽฏ Highlights](#-highlights) - [๐Ÿงญ Design Philosophy: imperfection by design](#-design-philosophy-imperfection-by-design) +- [๐ŸŽฏ Highlights](#-highlights) - [๐Ÿง  Concepts in 60 seconds](#-concepts-in-60-seconds) - [๐ŸŽฌ Demo](#-demo) - [๐Ÿ› ๏ธ Installation](#๏ธ-installation) @@ -50,13 +50,6 @@ --- -## ๐ŸŽฏ Highlights - -1. **๐Ÿ”ฎ Proactive Memory.** Proactivity is a property of the memory substrate, not the agent's policy โ€” goals emerge from the topology that accumulates the conditions for them. -2. **๐Ÿง  Architecture.** A tri-layered substrate extending Complementary Learning Systems with a prefrontal Intent layer โ€” events fold into concepts, concepts crystallize into intents, surfaced through a hierarchical context window. -3. **๐ŸŒฑ Conceptual Bootstrapping.** Accumulation, compression, decay, completion โ€” four structural debts of a streaming event log, resolved as transparent graph rewrites: test-time learning without gradient updates or surface text rewriting. -4. **๐Ÿ“Š Evaluation.** CogEval-Bench isolates proactive emergence from retrieval accuracy; seven downstream benchmarks confirm the substrate stays robust on conventional memory tasks. - ## ๐Ÿงญ Design Philosophy: imperfection by design CogniFold does **not** chase a perfect, omniscient, unbiased recall store. It models memory the way cognition actually works โ€” *situated, lossy, and opinionated* โ€” because that is precisely what makes proactivity possible. A system that stored everything with equal weight and perfect fidelity would be a database: faithful, and completely reactive. What lets memory *act ahead of you* is the same thing that makes it imperfect โ€” it decides what matters, what fades, and what crystallizes into an intent. **The bias is not a defect we are slowly engineering away. The bias is the mechanism.** We optimize for useful proactive structure, not for maximal ground-truth fidelity. @@ -70,6 +63,13 @@ Four cognitive realities we model **on purpose** instead of designing around: This is also why our reported benchmark numbers are the **proactive-substrate stack, not per-benchmark tuned ceilings**. Several older tasks are trivially inflatable with a task-specialized reader โ€” but that path rewards *auto-loop hallucination*, the reader confabulating to satisfy a metric instead of reading memory. That's exactly the metacognitive failure above, so we don't optimize for it. **The flaw is the point.** โ†’ Full writeup: [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md). +## ๐ŸŽฏ Highlights + +1. **๐Ÿ”ฎ Proactive Memory.** Proactivity is a property of the memory substrate, not the agent's policy โ€” goals emerge from the topology that accumulates the conditions for them. +2. **๐Ÿง  Architecture.** A tri-layered substrate extending Complementary Learning Systems with a prefrontal Intent layer โ€” events fold into concepts, concepts crystallize into intents, surfaced through a hierarchical context window. +3. **๐ŸŒฑ Conceptual Bootstrapping.** Accumulation, compression, decay, completion โ€” four structural debts of a streaming event log, resolved as transparent graph rewrites: test-time learning without gradient updates or surface text rewriting. +4. **๐Ÿ“Š Evaluation.** CogEval-Bench isolates proactive emergence from retrieval accuracy; seven downstream benchmarks confirm the substrate stays robust on conventional memory tasks. + ## ๐Ÿง  Concepts in 60 seconds CogniFold ingests an asynchronous event stream and folds it into a typed concept graph. Four node types โ€” the first three mirror Complementary Learning Systems (CLS) theory: