Cognitree — AI Memory System

How it works

The Cognitree Pipeline

Five stages that run on every prompt — turning a forgetful LLM into a precise, state-aware coding agent.

🧠

LLM Completes a Task

Claude Code, Qwen Code, or Gemini CLI produces output — code, a decision, a fix, an explanation. This output is the raw material Cognitree works from.

⚙️

Memory Extractor Parses Output

Cognitree scans the output and tags extracted data for the correct memory layer — decisions, mistakes, progress, state changes — each to its layer.

extract({ goal: "...", // active objective progress: [...], // what got done mistakes: [...], // what failed — permanent decisions: [...], // why X over Y warnings: [...], // be careful about codebase: {...}, // added, deleted, modified, renamed files prompt_state: {} // what AI believes right now })

🗄️

Checkpoint Written to Store

An immutable checkpoint is created — memory deltas, code deltas (diffs only), parent pointer, branch ID, confidence score. Full snapshot every 10 checkpoints. Deltas in between.

🎯

Context Injector Fires Before Next Prompt

Only relevant layers retrieved and injected. The AI reads a structured block with everything it needs — no re-derivation, no wasted tokens.

[COGNITREE — VoidRoom · cp_010b · branch-b · confidence 0.91] GOAL: Implement self-destructing messages with TTL expiry PROGRESS: Auth done, schema defined, UI scaffolded NEXT: Verify TTL index fires correctly with a test document MISTAKES: mongoose.findByIdAndDelete() → use findOneAndDelete() [critical] WARNINGS: TTL needs MongoDB background process running [medium] DECISION: TTL index over cron — atomic, native MongoDB (cp_010b) CODEBASE: /models/message.js [added cp_007] /models/user.js [added cp_003] /api/auth.js [added cp_004] /api/messages.js [added cp_010b] /client/src/App.js [added cp_002] /client/src/Chat.jsx [added cp_005] /utils/oldHelper.js [DELETED cp_008] /package.json /.env /README.md [/COGNITREE]

🚀

AI Works with Perfect Precision

The model knows exactly what was built, what failed, what was decided, and what to do next. Zero tokens wasted. Zero repeated mistakes. Zero hallucinations of known-bad paths.

Architecture

Ten Memory Layers

Everything a developer holds in their head while coding — now structured, persistent, and injected with precision before every prompt.

Layer 01 — Active

Goal

What we are building right now. The active objective for this session.

Current feature or fix in progress

Success criteria for this task

Layer 02 — Done

Progress

What is already completed. The AI never re-does finished work.

Completed features and merged logic

Files and modules already implemented

Layer 03 — Permanent

Mistakes

What went wrong. Never cleared. Never forgotten. Never repeated.

Hallucinated APIs and functions

Logic errors that caused bugs

Layer 04 — Blocked

Blockers

What is stuck or unresolved. Needs attention before moving forward.

Unsolved bugs or missing dependencies

Decisions waiting for input

Layer 05 — Immediate

The single immediate next step. One action at a time, always clear.

Exact next function or file to work on

Updated after every checkpoint

Layer 06 — History

Changed

What was updated or refactored and when. Full change log across sessions.

Refactored files with checkpoint reference

API changes, renames, and restructures

Layer 07 — Rationale

Decisions

Why X was chosen over Y. Architecture choices with full reasoning preserved.

Tech stack choices and trade-offs

Pattern choices with full reasoning

Layer 08 — Caution

Warnings

Fragile areas and edge cases. Forwarded into every new branch automatically.

Sensitive files or race conditions

Known gotchas in the stack

Layer 09 — Live

Prompt_State

The AI's active cognitive state. What it currently believes and assumes. Reset per checkpoint.

Active file and function in scope

Current approach and live assumptions

Layer 10 — Codebase

Codebase

The full codebase architecture. Every file, every directory, every addition, deletion, modification, and rename — tracked per checkpoint. Always fully injected. The AI never hallucinates a path that doesn't exist.

Full directory tree on every base checkpoint

Added files + directories with checkpoint ref

Deleted files stay in tree — marked deleted forever

Modified + renamed files tracked explicitly

Versioned Cognition

Checkpoint & Branch System

Every prompt is a commit growing downward. Branch from any node, on any branch, at any depth. Every node stays intact forever — unless you delete it manually.

// THE COGNITREE — HOW IT GROWS

  ● 1  ← root · all sessions begin here
  │
  ● 2
  │
  ● 3
  │
  ● 4
  │
  ● 5
  │
  ● 6
  │
  ● 7  ← developer rewinds here, not happy with direction
  │\
  │ \
  ● 8 ● 8a  ← new branch from 7, trunk continues untouched
  │ │
  ● 9 ● 9a
  │ │\
  │ │ \
  ●10 ✕10a ● 10b  ← 10a failed · branch again from 9a · branch of a branch
  │      │
  ●11     ● 11b  ← all nodes alive · developer switches freely
  │      │\
  │      │ \
  ●12    ●12b ● 12c  ← branch of branch of branch · unlimited depth

// SWITCHING TO ANY NODE

→ Jump to 10b — loads memory from 1→2→3...→9a→10b
→ Jump to 8 — loads memory from 1→2→3...→7→8
→ Jump to 12c — loads full lineage + all ancestor lessons
→ Nothing on other branches is touched or broken
→ Switch back anytime — every node is self-contained

// WHAT EACH NODE CARRIES

✓ All 9 memory layers at that exact moment
✓ Mistakes + Warnings from every ancestor
✓ Warnings forwarded from failed sibling branches
✓ Code state delta from parent checkpoint
✗ Sibling and descendant branches — invisible to AI

Checkpoint Structure

id: "cp_12c_f7a2"

parent_id: "cp_11b_..."

branch_id: "branch-c"

depth: 3 // branch of branch of branch

is_base: false // full snap every 10

confidence: 0.91 // branch health 0–1

memory_delta: {...} // changed layers only

code_delta: [...] // file diffs only

deleted: false // manual delete only

Delta Storage

● Full snapshot every 10 checkpoints
● Diffs only between base snapshots
● Unchanged files referenced, never copied
● Reconstruct = walk ancestors to nearest base
● All nodes permanent unless manually deleted
● ~95% storage reduction vs full snapshots

Compatibility

Works With Any Agent

Same memory engine, different injection adapters per tool. No lock-in. Use what you already have.

Claude Code

CLAUDE.md + MCP Server

Cognitree auto-writes memory into CLAUDE.md before each session. Also exposes all 9 memory layers as MCP tools Claude can read and write natively.

Qwen Code

Native Integration · Free

Open source — Cognitree integrates directly into Qwen Code's prompt pipeline. 1000 free API requests per day. No cost to start. Primary integration target.

Gemini CLI

GEMINI.md + State API

Open source — direct integration into prompt construction. GEMINI.md memory file plus Cognitree local state API. Bring your own Gemini API key.

Impact

Before vs After

The difference Cognitree makes in every session, on every project, with every AI tool.

Without Cognitree

✗Re-derives full project context every session

✗Repeats hallucinated API calls and wrong paths

✗No memory of prior decisions or rationale

✗~60% of tokens wasted re-establishing context

✗One error compounds into the whole session

✗No clean way to recover from a bad AI decision

With Cognitree

✓Instantly knows full project state from memory

✓Mistake layer permanently blocks known hallucinations

✓Understands WHY every decision was made

✓~85% of tokens used for actual productive work

✓Errors isolated per branch — clean recovery always

✓Rewind to any checkpoint, branch, start fresh

Roadmap

What's Being Built

VS Code extension first — zero friction for people already using Cursor and VS Code. IDE fork when the community is ready.

Phase 1

Memory Engine Core

Standalone memory store, 9 layers, checkpoint writer, delta storage, branch tree. No UI — pure engine.

BUILDING

Phase 2

VS Code Extension

Sidebar checkpoint tree, time travel UI, memory diff viewer, context injector. Works inside VS Code and Cursor — no IDE switch needed.

PLANNED

Phase 3

Agent Adapters

Native integration into Qwen Code and Gemini CLI source. CLAUDE.md + MCP server adapter for Claude Code. Bring your own key for Claude and Gemini.

PLANNED

Phase 4

Cognitree IDE

Code OSS fork with Qwen Code + Cognitree built in natively. Free forever for individuals. 1000 free Qwen requests/day. Claude and Gemini via API key.

PLANNED

Phase 5

Team Memory

Optional shared memory sync for collaborative projects. Organizational governance, audit, and compliance features. Individual core always free.

PLANNED