cognitive-kernel 2.0.0

Minimal, verifiable implementation of persistent long-term memory for AI agents

🧠 Cognitive Kernel

🇰🇷 한국어 | 🇺🇸 English

Minimal, verifiable implementation of persistent long-term memory for AI agents.

기억의 시간 인코딩(Temporal Encoding), 중요도 랭킹(Importance Ranking), 의사결정 반영(Decision Impact)을 결합한 모듈형 인지 프레임워크.

---

🎯 왜 지금 필요한가?

현대 LLM 에이전트에는 구조화된 장기 기억과 실행 제어 기능이 부족합니다.

Cognitive Kernel은 이 갭을 메우기 위한 drop-in 인지 서브시스템을 제공합니다.

⚠️ 연구 및 실험 도구입니다.
   실제 뇌의 완전한 모델이 아니며, 임상 진단 도구가 아닙니다.

📌 This project does not claim biological equivalence to human memory.
   It provides a computer-science definition of long-term memory:
   persistent, structured, recallable, and decision-impacting.

---

⭐ 핵심 기능: 3줄로 시작하는 장기 기억

from cognitive_kernel import CognitiveKernel

with CognitiveKernel("my_brain") as kernel:
    kernel.remember("meeting", {"topic": "project"}, importance=0.9)
    memories = kernel.recall(k=5)           # PageRank 기반 중요도 회상
    decision = kernel.decide(["rest", "work"])  # Softmax 의사결정
# 자동 저장됨 → 프로세스 종료 후에도 기억 유지

✅ 이것만으로:

기능	설명	알고리즘
remember()	기억 저장 (장기 기억)	시간축 저장 + 자동 영속성
recall()	중요한 기억 회상	Google PageRank
decide()	의사결정	Softmax Utility

→ 장기 기억 상세 설명

---

📐 핵심 수식

1. 기억 중요도 (MemoryRank)

Personalized PageRank 알고리즘:

$$ \mathbf{r}^{(t+1)} = \alpha \cdot M \cdot \mathbf{r}^{(t)} + (1-\alpha) \cdot \mathbf{v} $$

• $\mathbf{r}$: 기억 중요도 벡터
• $M$: 기억 전이 행렬 (열 정규화)
• $\alpha$: 감쇠 계수 (기본값: 0.85)
• $\mathbf{v}$: 개인화 벡터 (recency, emotion, frequency 가중치)

2. 시간 감쇠 (Panorama)

지수 감쇠 함수:

$$ S(t) = S_0 \cdot e^{-\lambda \cdot \Delta t}, \quad \lambda = \frac{\ln 2}{t_{1/2}} $$

• $S(t)$: 시간 $t$에서의 중요도
• $t_{1/2}$: 반감기 (기본값: 3600초 = 1시간)

3. 의사결정 (PFC)

Softmax 선택 확률:

$$ P(a_i) = \frac{e^{U(a_i) / T}}{\sum_j e^{U(a_j) / T}} $$

• $U(a)$: 행동 $a$의 효용 = 기대보상 - 비용 - 위험
• $T$: 온도 (탐색 vs 착취 균형)

→ 이론적 기반 상세

---

💾 장기 기억이란?

컴퓨터 공학적 정의

영속성(Persistence): 프로세스 종료 후에도 데이터가 유지됨

Cognitive Kernel의 구현

세션 A (프로세스 1)          세션 B (프로세스 2)
─────────────────────      ─────────────────────
kernel.remember(...)  →    파일 저장
        ↓                       ↓
프로세스 종료              CognitiveKernel("my_brain")
                                ↓
                           자동 로드 → 기억 복구!

저장 구조

.cognitive_kernel/my_brain/
├── panorama.json      # 시간축 이벤트 (기억 데이터)
├── memoryrank.json    # 중요도 그래프
├── edges.json         # 기억 연결 관계
├── q_values.json      # 습관 학습 (Q-Learning)
└── meta.json          # 세션 메타데이터

→ 장기 기억 기술 문서

---

🧪 테스트 결과

장기 기억 증명

# 테스트 실행
cd /Users/jazzin/Desktop/00_BRAIN/Cognitive_Kernel
python3 cognitive_kernel.py

결과:

📦 Session: test_session
📝 기억 저장... 3개
🔍 기억 회상 (Top 3): idea(0.349), conversation(0.333), meeting(0.318)
🎯 의사결정: rest (효용: 0.250)
✅ 자동 저장 완료!

🔄 세션 복구 테스트...
   복구된 이벤트: 3개 ← 프로세스 종료 후에도 유지됨!

7개 엔진 통합 시뮬레이션

시나리오	Stress Max	Hyperarousal	Efficiency	Alerts
Normal Day	0.44	1회	0.71	1개
PTSD	0.80	3회	0.61	5개

→ 전체 테스트 결과

---

📦 전체 모듈 구성

모듈	역할	핵심 알고리즘	영속성
MemoryRank	기억 중요도	PageRank	✅ JSON/NPZ
Panorama	시간축 기억	Exponential Decay	✅ JSON/SQLite
PFC	의사결정	Softmax Utility
BasalGanglia	습관 학습	TD-Learning	✅ Q-values
Amygdala	감정/위협	Rescorla-Wagner
Hypothalamus	에너지/스트레스	HPA Dynamics
Thalamus	입력 필터링	Salience Gating

---

🔧 활용 방향

🔬 연구용 (Research)

• 인지 모델 시뮬레이션
• 기억-감정-의사결정 동역학 연구
• 뇌 질환 메커니즘 탐구 (PTSD, ADHD 등)

🏭 산업용 (Industrial)

• AI 에이전트 메모리 서브시스템
• RAG 검색 결과 필터링/랭킹
• LangChain/LlamaIndex 통합

💼 상업용 (Commercial)

• 개인화된 AI 비서의 기억 레이어
• 게임 NPC 행동 엔진
• 교육용 시뮬레이터

---

🔗 설계 철학

Edge AI First

✅ 경량 알고리즘 (NumPy 외 필수 의존성 없음)
✅ 모듈별 독립 실행 가능
✅ 클라우드 의존성 없음
✅ 확장 가능한 구조

모듈 조합

# 1개만 사용
from memoryrank import MemoryRankEngine

# 조합해서 사용
from cognitive_kernel import CognitiveKernel

# 직접 확장
class MyBrain(CognitiveKernel):
    def custom_recall(self): ...

---

🚀 Quick Start

git clone https://github.com/qquartsco-svg/Cognitive_Kernel.git
cd Cognitive_Kernel
pip install numpy

# 장기 기억 테스트
python3 cognitive_kernel.py

# 7개 엔진 통합 시뮬레이션
python3 examples/full_brain_simulation.py

# 4개 핵심 파이프라인
python3 examples/integrated_pipeline.py

---

📚 문서

문서	설명
LONG_TERM_MEMORY.md	장기 기억 기술 문서
API_REFERENCE.md	API 레퍼런스
ARCHITECTURE.md	이론적 기반, 수식, 참고 문헌
TEST_RESULTS.md	전체 테스트 결과
VERIFICATION_STATUS.md	이론 ↔ 코드 일치 검증

---

🔐 PHAM Blockchain Signature

모든 핵심 모듈은 PHAM (Proof of Honest Authorship & Merit) 블록체인으로 서명:

모듈	서명	등급
cognitive_kernel.py	✅	A_HIGH (0.9998)
MemoryRank	✅	서명
Panorama	✅	서명
PFC	✅	서명

---

📄 License

MIT License — 자유롭게 사용, 수정, 배포 가능

---

👤 Author

GNJz (Qquarts) — @qquartsco-svg

---

---

English Version

🇰🇷 한국어 | 🇺🇸 English

Minimal, verifiable implementation of persistent long-term memory for AI agents.

A modular cognitive framework combining Temporal Encoding, Importance Ranking, and Decision Impact.

---

🎯 Why Now?

Modern LLM agents lack structured long-term memory and executive control.

Cognitive Kernel provides drop-in cognitive subsystems to address this gap.

⚠️ Research and experimentation tool.
   NOT a complete model of the brain, nor a clinical diagnostic tool.

📌 This project does not claim biological equivalence to human memory.
   It provides a computer-science definition of long-term memory:
   persistent, structured, recallable, and decision-impacting.

---

⭐ Core Feature: Long-term Memory in 3 Lines

from cognitive_kernel import CognitiveKernel

with CognitiveKernel("my_brain") as kernel:
    kernel.remember("meeting", {"topic": "project"}, importance=0.9)
    memories = kernel.recall(k=5)           # PageRank-based importance recall
    decision = kernel.decide(["rest", "work"])  # Softmax decision-making
# Auto-saved → Memory persists after process termination

✅ This gives you:

Feature	Description	Algorithm
remember()	Store memory (long-term)	Timeline storage + auto-persistence
recall()	Recall important memories	Google PageRank
decide()	Decision making	Softmax Utility

→ Long-term Memory Details

---

📐 Core Formulas

1. Memory Importance (MemoryRank)

Personalized PageRank algorithm:

$$ \mathbf{r}^{(t+1)} = \alpha \cdot M \cdot \mathbf{r}^{(t)} + (1-\alpha) \cdot \mathbf{v} $$

• $\mathbf{r}$: Memory importance vector
• $M$: Memory transition matrix (column-normalized)
• $\alpha$: Damping factor (default: 0.85)
• $\mathbf{v}$: Personalization vector (recency, emotion, frequency weights)

2. Temporal Decay (Panorama)

Exponential decay function:

$$ S(t) = S_0 \cdot e^{-\lambda \cdot \Delta t}, \quad \lambda = \frac{\ln 2}{t_{1/2}} $$

• $S(t)$: Importance at time $t$
• $t_{1/2}$: Half-life (default: 3600s = 1 hour)

3. Decision Making (PFC)

Softmax selection probability:

$$ P(a_i) = \frac{e^{U(a_i) / T}}{\sum_j e^{U(a_j) / T}} $$

• $U(a)$: Utility of action $a$ = expected reward - cost - risk
• $T$: Temperature (exploration vs exploitation balance)

→ Theoretical Foundation

---

💾 What is Long-term Memory?

Computer Science Definition

Persistence: Data survives process termination

Cognitive Kernel Implementation

Session A (Process 1)          Session B (Process 2)
─────────────────────         ─────────────────────
kernel.remember(...)  →       File saved
        ↓                          ↓
Process terminates            CognitiveKernel("my_brain")
                                   ↓
                              Auto-load → Memory recovered!

Storage Structure

.cognitive_kernel/my_brain/
├── panorama.json      # Timeline events (memory data)
├── memoryrank.json    # Importance graph
├── edges.json         # Memory connections
├── q_values.json      # Habit learning (Q-Learning)
└── meta.json          # Session metadata

→ Long-term Memory Technical Docs

---

🧪 Test Results

Long-term Memory Proof

# Run test
cd /Users/jazzin/Desktop/00_BRAIN/Cognitive_Kernel
python3 cognitive_kernel.py

Result:

📦 Session: test_session
📝 Memories saved: 3
🔍 Recall (Top 3): idea(0.349), conversation(0.333), meeting(0.318)
🎯 Decision: rest (utility: 0.250)
✅ Auto-saved!

🔄 Session recovery test...
   Recovered events: 3 ← Persists after process termination!

7-Engine Integration Simulation

Scenario	Stress Max	Hyperarousal	Efficiency	Alerts
Normal Day	0.44	1	0.71	1
PTSD	0.80	3	0.61	5

→ Full Test Results

---

📦 All Modules

Module	Role	Core Algorithm	Persistence
MemoryRank	Memory importance	PageRank	✅ JSON/NPZ
Panorama	Timeline memory	Exponential Decay	✅ JSON/SQLite
PFC	Decision making	Softmax Utility
BasalGanglia	Habit learning	TD-Learning	✅ Q-values
Amygdala	Emotion/Threat	Rescorla-Wagner
Hypothalamus	Energy/Stress	HPA Dynamics
Thalamus	Input filtering	Salience Gating

---

🔧 Use Cases

🔬 Research

• Cognitive model simulation
• Memory-emotion-decision dynamics research
• Brain disorder mechanism exploration (PTSD, ADHD, etc.)

🏭 Industrial

• AI agent memory subsystem
• RAG result filtering/ranking
• LangChain/LlamaIndex integration

💼 Commercial

• Personalized AI assistant memory layer
• Game NPC behavior engine
• Educational simulators

---

🔗 Design Philosophy

Edge AI First

✅ Lightweight algorithms (only NumPy dependency)
✅ Each module runs independently
✅ No cloud dependency
✅ Extensible structure

Module Composition

# Use one
from memoryrank import MemoryRankEngine

# Combine
from cognitive_kernel import CognitiveKernel

# Extend
class MyBrain(CognitiveKernel):
    def custom_recall(self): ...

---

🚀 Quick Start

git clone https://github.com/qquartsco-svg/Cognitive_Kernel.git
cd Cognitive_Kernel
pip install numpy

# Long-term memory test
python3 cognitive_kernel.py

# 7-engine simulation
python3 examples/full_brain_simulation.py

# 4-engine pipeline
python3 examples/integrated_pipeline.py

---

📚 Documentation

Document	Description
LONG_TERM_MEMORY.md	Long-term memory technical docs
API_REFERENCE.md	API Reference
ARCHITECTURE.md	Theoretical foundation, formulas, references
TEST_RESULTS.md	Full test results
VERIFICATION_STATUS.md	Theory ↔ Code verification

---

🔐 PHAM Blockchain Signature

All core modules signed with PHAM (Proof of Honest Authorship & Merit) blockchain:

Module	Signed	Grade
cognitive_kernel.py	✅	A_HIGH (0.9998)
MemoryRank	✅	Signature
Panorama	✅	Signature
PFC	✅	Signature

---

📄 License

MIT License — Free to use, modify, and distribute

---

👤 Author

GNJz (Qquarts) — @qquartsco-svg

---

🤝 Contributing

Contributions welcome! Please open an issue or submit a Pull Request.