NekoCore OS

A COGNITIVE OPERATING SYSTEM

A cognitive WebOS for persistent AI identity — episodic memory, belief formation,
dream processing, and layered reasoning, built on the R.E.M. System.

2,816	1	5	31
Tests Passing	Runtime Dep	Pipeline Phases	Desktop Apps

⚒ Phase 6 — Forge & Polish

The raw metal becomes the blade.
All new features halted. Every bug gets crushed. Every edge gets filed.

Caution

PRE-ALPHA SOFTWARE — KNOWN BUGS EXIST

NekoCore OS is in pre-alpha. All subsystems are functional but bugs and rough edges remain. We know about them — and we've halted all new feature work to fix them.

Phase 6: Forge & Polish is now active — a dedicated stability pass to crush every known issue, harden error recovery, and polish the entire system for real-world use.

APIs, data formats, and behaviour may change without notice between releases. Active bug tracking: docs/CURRENT-BUGS.md

Before experimenting: back up your entities/ and memories/ folders.

Python is NOT required. The only runtime dependency is Node.js 18+.

"A system that stores interaction history but applies no policy about which part of the past should govern current behavior is not a continuity architecture — it is a log browser."

Core conviction: an entity should be shaped by what it has experienced, not only by what it was told on day one.

📸 Screenshots

NekoCore OS — Web Browser

The full cognitive desktop running in your browser — entity chat, Start menu, taskbar, and 31 windowed apps.

NekoCore OS running in web browser

Entity Chat & Identity

Entity profile with personality traits and active skills alongside live cognitive chat.

NekoCore OS entity chat and identity

╱╱ Neural Cognitive Graph

See what your entity is thinking.

Every pipeline phase fires a pulse through the 3D WebGL graph — memory retrieval, dream associations, conscious reasoning, and final voicing all light up as distinct node clusters in real time.

◇ Live SSE events drive node activation
◇ Edge weights reflect memory topology connections
◇ Color channels map to pipeline phases
◇ Rotate, zoom, inspect — full Three.js interaction

3D Neural Visualizer

WebGL cognitive graph — nodes pulse with live pipeline events.

3D neural visualizer

QA Checklist & Bug Tracker

625-item QA checklist with pass/fail tracking alongside the bug tracker with severity and export.

╱╱ Quality & Issue Tracking

Ship with confidence.

The QA Checklist covers 625 test items across 61 sections — every subsystem, every edge case, with pass/fail/untested state and persistent progress tracking.

◇ Bug Tracker with screenshot capture + severity + Markdown export
◇ Progress bars and per-section completion counts
◇ Save/load results as JSON for CI or manual QA runs
◇ Filter by pass, fail, or untested across all sections

Physical / Neurochemistry

Real-time dopamine, cortisol, serotonin, and oxytocin levels shaping entity mood and tone.

Physical and neurochemistry panel

Profiler

Pipeline timing, token usage, and per-phase performance breakdown.

Profiler panel

Start Menu & App Launcher

31 desktop apps organized by category — search, pin, and launch from one place.

╱╱ 31 Desktop Applications

A full operating system, not just a chatbot.
Every app runs in its own draggable, resizable window with minimize, maximize, snap-dock, and pop-out support.

╱╱ Memory Architect (MA)

A full AI coding assistant — inside the OS.
Built-in browser IDE with blueprint execution, agent delegation, deep research, and workspace management.

Memory Architect — Browser IDE

Blueprint execution, file explorer, chat, and terminal in one window.

Memory Architect IDE running inside NekoCore OS

✦ Core Capabilities

🧠 Episodic Memory Echoes — structured memory fragments across three tiers (episodic, semantic, long-term) with salience decay curves, reinforcement on recall, and automatic divergence repair.	🌙 Dream Processing Phase 1D dream-intuition runs concurrently with every turn. Offline REM sleep consolidates memory, updates beliefs, and generates dream narratives.	🔮 Belief Graph Beliefs emerge from memory cross-reference — not hand-authored. Each carries a confidence weight and source echoes. New evidence shifts strength dynamically.
⚗️ Neurochemistry Dopamine, cortisol, serotonin, and oxytocin simulate in real time and modulate every response. Graduated mood shift proportional to interaction magnitude.	🪪 Entity Hatching Structured multi-phase birth — name → traits → life history → core memories → goals. Unbreakable Mode locks the origin post-hatch for fixed characters.	🔌 Skills & Routing Drop-in function-call plugins with per-phase model routing. Assign different LLMs to 1A, 1D, 1C, and Final. Ollama, OpenRouter, and Anthropic Direct supported.
⚡ Token Optimization Hybrid router, NLP memory encoding, prompt compression, and semantic caching cut ~68% of per-turn token usage across four optimization phases.	🧬 Cognitive State Pre-turn snapshot assembles beliefs, goals, mood, diary, and curiosity. Post-turn feedback reinforces beliefs, tracks goals, resolves curiosity, and nudges neurochemistry.	📋 Task Orchestration Slash commands (`/task`, `/skill`, `/project`, `/websearch`, `/ma`) dispatch structured work. The Frontman bridge translates progress into entity-voice messages.
🏗️ Memory Architect Built-in AI coding assistant with browser IDE, blueprint-driven project execution, agent delegation, deep research, terminal access, and workspace management.	🔗 Predictive Memory Memory topology with shape classification, edge graphs, activation propagation, and dream reconsolidation. Echo Future predicts relevant memories before needed.	🔑 Anthropic Direct Native Anthropic Messages API with prompt caching (up to 90% savings), extended thinking, native tool use, and provider-agnostic capability layer.

⟁ Cognitive Architecture

┌──────┬──────────────────────┬─────────────────────────────────────┐
│  L5  │  Final Orchestrator  │  personality · neurochemistry        │
│  L4  │  Conscious  (1C)     │  reasoning with full memory context  │
│  L3  │  Dream-Intuition(1D) │  abstract associations (parallel)    │
│  L2  │  Subconscious  (1A)  │  memory retrieval, context assembly  │
│  L1  │  Brain Loop          │  decay · goals · REM trigger         │
└──────┴──────────────────────┴─────────────────────────────────────┘

Cognitive Pipeline

flowchart TD
    A["🎤 User Input"] --> B{"Turn Classifier\n(hybrid router)"}
    B -->|Simple| C["⚡ Template Response"]
    B -->|Complex| D["Phase 1A\n🧠 Subconscious\nmemory retrieval"]
    B -->|Complex| E["Phase 1D\n🌙 Dream-Intuition\nabstract associations"]
    D --> F["Phase 1C\n💭 Conscious\nreasoning · full context"]
    E --> F
    F --> G["Final Orchestrator\n🎭 Voicing\npersonality · neurochemistry"]
    C --> H["💬 Response → User"]
    G --> H
    H -.->|async| I["📝 NLP Memory Encoding\n🔄 Cognitive Feedback\n💕 Relationship Update"]

    style A fill:#fbbf24,stroke:#92400e,color:#000
    style B fill:#1a1726,stroke:#8b5cf6,color:#e8e4f0
    style C fill:#1a1726,stroke:#34d399,color:#34d399
    style D fill:#1a1726,stroke:#34d399,color:#34d399
    style E fill:#1a1726,stroke:#22d3ee,color:#22d3ee
    style F fill:#1a1726,stroke:#ec4899,color:#ec4899
    style G fill:#1a1726,stroke:#8b5cf6,color:#8b5cf6
    style H fill:#fbbf24,stroke:#92400e,color:#000
    style I fill:#1a1726,stroke:#6b6280,color:#9d95b0

Brain Loop

The brain loop ticks independently of conversation:

flowchart LR
    subgraph BrainLoop["🔄 Brain Loop — Background Ticker"]
        direction LR
        M["Memory\nConsolidation"] --> BF["Belief\nFormation"]
        BF --> GR["Goal\nReview"]
        GR --> CE["Curiosity\nEngine"]
        CE --> RS["REM Sleep\nTrigger"]
        RS --> ND["Neurochemistry\nDrift"]
        ND --> SA["Somatic\nAwareness"]
        SA --> M
    end

    style BrainLoop fill:#0e0c15,stroke:#2a2540,color:#e8e4f0
    style M fill:#1a1726,stroke:#8b5cf6,color:#8b5cf6
    style BF fill:#1a1726,stroke:#ec4899,color:#ec4899
    style GR fill:#1a1726,stroke:#34d399,color:#34d399
    style CE fill:#1a1726,stroke:#22d3ee,color:#22d3ee
    style RS fill:#1a1726,stroke:#fbbf24,color:#fbbf24
    style ND fill:#1a1726,stroke:#fb7185,color:#fb7185
    style SA fill:#1a1726,stroke:#8b5cf6,color:#8b5cf6

📊 Project Metrics

Test Suite Growth

xychart-beta
    title "Test Suite Growth by Phase"
    x-axis ["Phase 3", "4.0", "4.8", "4.16", "4.24", "Phase 5"]
    y-axis "Passing Tests" 0 --> 3000
    bar [866, 950, 1200, 2012, 2247, 2816]

Token Optimization — ~68% Reduction

Each phase stacks on the last, progressively eliminating unnecessary LLM calls and token waste:

Phase	Strategy	Savings Per Turn	Applies To
1	NLP memory encoding + reranker bypass	~2,700 tokens	All turns
2	Hybrid router diverts simple turns	~15,000 tokens	~60% of casual turns
3	Prompt compression across all 4 nodes	~4,700–9,300 tokens	All complex turns
4	Semantic cache for similar inputs	~16,000 tokens	Cache hits

xychart-beta
    title "Tokens Saved Per Turn by Optimization Phase"
    x-axis ["Phase 1: NLP", "Phase 2: Router", "Phase 3: Compress", "Phase 4: Cache"]
    y-axis "Tokens Saved" 0 --> 18000
    bar [2700, 15000, 7000, 16000]

Memory Architecture

Layer	Type	Decay	Contents
Episodic	JSON echo files	✓ Salience curve	Specific events and interactions
Semantic	JSON echo files	✓ Slower	Concepts, facts, generalizations
Long-Term	Compressed chatlog chunks	✗	Full conversation history (chunked)
Context	Assembled `.md` file	Rebuilt each turn	Ranked retrieval block sent to LLM

pie title Memory Tier Distribution
    "Episodic (active recall)" : 40
    "Semantic (concepts)" : 25
    "Long-Term (compressed)" : 25
    "Context (rebuilt/turn)" : 10

Neurochemistry Engine

Chemical	High State	Low State	Modulates
⚡ Dopamine	Energetic, curious	Flat, disengaged	Drive & curiosity tone
🛡️ Cortisol	Guarded, stressed	Relaxed, open	Caution & defensive phrasing
☀️ Serotonin	Stable, warm	Unstable, irritable	Emotional baseline
💜 Oxytocin	Warm, connected	Detached	Social tone & relational warmth

Pipeline Token Budget

pie title Estimated Per-Turn Token Allocation
    "Subconscious (1A)" : 30
    "Conscious (1C)" : 35
    "Final Orchestrator" : 20
    "Dream-Intuition (1D)" : 10
    "Brain Loop" : 5

⟶ Development Roadmap

35 feature phases complete. Phase 6: Forge & Polish is active — all new features halted while we crush every bug and harden every subsystem:

timeline
    title NekoCore OS Development Phases
    section Foundation
        Phase 1  : Bug Fixes
        Phase 2  : Refactor / Cleanup
        Phase 3  : Full App Modularization (866 tests)
        Phase 4  : Feature Foundation
    section Memory & Cognition
        Phase 4.5  : Intelligent Memory Expansion
        Phase 4.6  : Slash Command System
        Phase 4.7  : HTML Shadow Cleanup
        Phase 4.8  : Cognitive State + Token Optimization (~68% reduction)
    section Orchestration
        Phase 4.9   : Task Orchestration (MTOA)
        Phase 4.10  : Entity Orchestration
        Phase 4.11  : Blueprint System
        Phase 4.12  : Coding Skill + Project Executor
    section Resilience
        Phase 4.13 : Health Scanner + Fixer Generator
        Phase 4.14 : Sandboxed Code Execution
        Phase 4.15 : BIOS + Failsafe (300 registry entries)
        Phase 4.16 : Self-Repair Skill (2,012 tests)
    section Expansion
        Phase 4.17 : OS Tool Upgrade
        Phase 4.18 : Entity Genesis Skill
        Phase 4.19 : MA Bridge
        Phase 4.20 : Bug Tracker App
        Phase 4.21 : Resource Manager App
        Phase 4.22 : Smart Port Management
    section Polish
        Phase 4.23 : User Documentation (24 sections)
        Phase 4.24 : MA Public Release (2,247 tests)
        Phase 4.25 : Provider-Agnostic Capabilities
        Phase 4.26 : QA Checklist (625 items)
    section Intelligence
        Phase 4.27 : MA Skills GUI
        Phase 4.28 : Prompt Engineering Blueprint
        Phase 4.29 : App Builder Blueprint
        Phase 4.30 : Blueprint Builder Meta-Blueprint
        Phase 4.31 : D&D + Study Blueprints
        Phase 4.32 : Book-to-Entity Ingestion
        Phase 4.33 : Bug Tracker Export
        Phase 5   : Predictive Memory Topology (2,816 tests)
    section Forge & Polish
        Phase 6 : 🔥 Bug Crush · Stability Hardening · Refactor

↓ Installation

Prerequisites

Node.js 18+ — the only runtime requirement
An LLM provider — Ollama (local), OpenRouter, or Anthropic API key
Python 3 — NOT required. Only used by the optional neko_fixer.py emergency tool

Quick Start

# 1. Clone
git clone https://github.com/voardwalker-code/NekoCore-OS.git

# 2. Install (one dependency: Zod)
cd NekoCore-OS/project
npm install

# 3. Launch
npm start

Open http://localhost:3847 in your browser.

Configure Your LLM Provider

cp Config/ma-config.example.json Config/ma-config.json

Ollama (local)

{
  "provider": "ollama",
  "ollamaBaseUrl": "http://localhost:11434",
  "defaultModel": "mistral"
}

OpenRouter (cloud)

{
  "provider": "openrouter",
  "openRouterApiKey": "sk-or-...",
  "defaultModel": "mistralai/mistral-7b-instruct"
}

Anthropic Direct

{
  "provider": "anthropic",
  "apiKey": "sk-ant-...",
  "defaultModel": "claude-sonnet-4-20250514"
}

Recommended Multi-Phase Model Routing

Route each pipeline phase to a specialized model for best results:

Phase	Recommended Model	Why
main / conscious (1C)	`inception/mercury-2`	Fast, strong reasoning
subconscious (1A)	`inception/mercury-2`	Context assembly, memory retrieval
dream (1D)	`google/gemini-2.5-flash`	Abstract association — cheap is fine
background	`google/gemini-2.5-flash`	Brain loop — high frequency
orchestrator (final)	`anthropic/claude-sonnet-4.6`	Final voicing — quality matters

Full multi-phase profile JSON

{
  "profiles": {
    "BEST": {
      "main":         { "type": "openrouter", "model": "inception/mercury-2" },
      "subconscious": { "type": "openrouter", "model": "inception/mercury-2" },
      "dream":        { "type": "openrouter", "model": "google/gemini-2.5-flash" },
      "background":   { "type": "openrouter", "model": "google/gemini-2.5-flash" },
      "orchestrator": { "type": "openrouter", "model": "anthropic/claude-sonnet-4.6" }
    }
  }
}

◌ Usage

Browser UI

Surface	Description
`/` — Chat	Main entity chat interface
`/` — Memory tab	Browse episodic, semantic, and LTM echoes
`/` — Belief tab	Inspect emergent beliefs
`/` — Dream Gallery	View and replay recorded dreams
`/` — Diary	Entity self-reflection log
`/` — Sleep tab	Trigger REM cycle, view sleep history
`/` — Bug Tracker	Screenshot capture, severity tracking, Markdown export
`/` — Resource Manager	Task/project tracking for active entities
`/` — QA Checklist	625 test items, progress tracking, JSON export
`/` — MA Server	Memory Architect control panel
`/visualizer.html`	3D WebGL neural cognitive state graph

Creating an Entity

Open the browser UI
Click New Entity
Follow the hatching wizard: name → traits → life history → goals
The entity is ready to chat once hatching completes

Skills

Skills live in project/skills/<name>/. The entity's LLM invokes them via function call syntax:

Skill	Description
`web-search`	Search the web and summarize results
`memory-tools`	Query, tag, or reinforce specific memories
`search-archive`	Search archived conversation history
`coding`	Write, run, test, and debug code projects
`entity-genesis`	Guided multi-round entity creation wizard
`self-repair`	Diagnose and fix NekoCore's own system
`python` / `rust`	Language-specific programming skills
`ws_mkdir` / `ws_move`	Workspace file operations

Self-Repair & Failsafe

Tool	What It Does	Requires
Health Scanner (`node scripts/health-scan.js`)	Scans 300 core files for missing/corrupt entries	Node.js
Fixer Generator (`node scripts/generate-fixer.js`)	Produces `neko_fixer.py` — a standalone rebuild script	Node.js
neko_fixer.py	Restores missing/corrupt files from embedded DNA hashes	Python 3 (stdlib only)
Failsafe Console (`/failsafe.html`)	Zero-dependency emergency WebGUI — auth, LLM setup, chat	Browser

Memory Architect (MA)

MA is a built-in AI coding assistant at project/MA/. Start it from NekoCore OS via the /ma slash command, the Start menu, or standalone:

cd project/MA && npm install && npm start

MA ships with blueprints for two companion projects: REM System Core and NekoCore Cognitive Mind. See project/MA/README.md for the full guide. Also available as a standalone repo.

◧ Cognitive Bus (SSE Events)

All pipeline activity streams over SSE — nothing the entity thinks is hidden from the developer:

Event	Description
`1a_start` / `1a_done`	Subconscious phase markers
`1d_start` / `1d_done`	Dream-intuition phase markers
`1c_start` / `1c_done`	Conscious phase markers
`final_start` / `final_done`	Final orchestrator markers
`orchestration_complete`	Full pipeline finished (includes token counts)
`turn_classified`	Hybrid router classification result
`cache_hit`	Semantic cache hit — cached response reused
`memory_write`	Echo newly encoded
`belief_update`	Belief created or reinforced
`chemistry_update`	Neurochemical state delta
`sleep_start` / `sleep_done`	REM cycle boundaries
`dream_fragment`	Dream narrative fragment emitted

◎ API Reference

Method	Endpoint	Description
`POST`	`/api/chat`	Send a message, get a response
`GET`	`/api/entities`	List all entities
`POST`	`/api/entities`	Create a new entity
`GET`	`/api/entities/:id`	Get entity state
`POST`	`/api/entities/:id/sleep`	Trigger REM sleep cycle
`GET`	`/api/entities/:id/memories`	List memories
`GET`	`/api/entities/:id/beliefs`	List beliefs
`GET`	`/api/entities/:id/dreams`	List dreams
`GET`	`/api/entities/:id/diary`	Self-reflection log
`GET`	`/api/entities/:id/relationships`	Per-user relationship records
`POST`	`/api/task/run`	Dispatch a task
`GET`	`/api/task/session/:id`	Task session details
`POST`	`/api/auth/login`	Authenticate
`GET`	`/events`	SSE cognitive bus stream

◧ Project Structure

NekoCore-OS/
├── README.md
├── docs/
│   ├── CHANGELOG.md                    # Release notes
│   ├── WORKLOG.md                      # Active process and phase ledger
│   ├── BUGS.md                         # Bug queue and status tracking
│   ├── AGENTS.md                       # Agent operating rules
│   ├── USER-GUIDE.md                   # 24-section user guide
│   ├── NEKOCORE-OS-WHITE-PAPER-v2.md   # Technical white paper
│   └── NEKOCORE-OS-ARCHITECTURE-v1.md  # Architecture reference
└── project/
    ├── client/                # Browser frontend (desktop shell + 31 apps)
    ├── server/                # Backend server
    ├── skills/                # 11 pluggable skill plugins
    ├── scripts/               # Health scanner, fixer generator
    ├── tests/                 # 2,816 passing tests
    ├── MA/                    # Memory Architect — AI coding assistant
    │   ├── MA-Server.js       #   HTTP server (port 3850)
    │   ├── MA-server/         #   Core modules
    │   ├── MA-client/         #   Browser GUI
    │   ├── MA-blueprints/     #   Build blueprints
    │   └── MA-workspace/      #   Project scaffolds
    ├── Config/                # Runtime config
    ├── entities/              # Runtime entity data (gitignored)
    └── memories/              # System memory (gitignored)

◈ Technical Specification

Capability	Detail
Runtime	Pure Node.js 18+ — one dependency (Zod), no Express, no frameworks
Persistence	File-system JSON — no database required
Memory	Episodic · Semantic · Long-Term (compressed chatlog chunks)
Pipeline	1A (subconscious) · 1D (dream) · 1C (conscious) · Final · Brain Loop
LLM Support	Ollama (local) · OpenRouter · Anthropic Direct · Any OpenAI-compatible
Realtime	SSE cognitive bus — all pipeline events streamed to browser
Visualizer	Three.js WebGL 3D neural node graph
Memory Topology	Shape classification · Edge graphs · Activation propagation
Test Suite	2,816 passing — unit + integration

◉ Reset / Uninstall

# Reset all entity data (keeps server code)
node reset-all.js

# Full uninstall
cd .. && rm -rf NekoCore-OS

⬡ Why NekoCore? Why Open Source?

Right now, AI feels like the moment the wheel was invented. But instead of building cars, most people are still waiting for a bigger, better wheel. We have barely begun to explore what we can build with what already exists.

NekoCore exists because I wanted to see what I could build with this new wheel. I open-sourced it because I want to see what you can do with more!

⚖ Copyright and Community Safety

NekoCore is MIT licensed and intended for safe open-source collaboration. See LICENSE for details.

The in-shell browser app uses an embedded page model — some sites block embedding by policy. Browser data and REM memory are separate by default; visiting a page does not automatically write to REM memory.

♡ Projects I Love

Project	Why I Love It
PowerInfer	Fast LLM inference on consumer GPUs — hot/cold neuron splitting across CPU/GPU. 11x faster than llama.cpp on a single RTX 4090. Also building Tiiny AI Pocket Lab, a pocket-size local-AI supercomputer.
OpenClaw	Personal AI assistant you run on your own devices. Multi-channel inbox (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, and more), voice wake, live canvas, and a local-first gateway. The lobster way. 🦞

☕ Support NekoCore

NekoCore is free, open-source, and built by one developer fueled by curiosity, caffeine, and API tokens.
If this project sparks something for you, a small tip helps keep the neurons firing.

Every token goes toward LLM API calls, infrastructure, and late-night pizza. 🐱

MIT Licensed — Use it, fork it, extend it, build on it.

Website · User Guide · White Paper · Architecture · Memory Architect · Support

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
project		project
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

NekoCore OS

⚒ Phase 6 — Forge & Polish

📸 Screenshots

NekoCore OS — Web Browser

Entity Chat & Identity

╱╱ Neural Cognitive Graph

3D Neural Visualizer

QA Checklist & Bug Tracker

╱╱ Quality & Issue Tracking

Physical / Neurochemistry

Profiler

Start Menu & App Launcher

╱╱ 31 Desktop Applications

╱╱ Memory Architect (MA)

Memory Architect — Browser IDE

✦ Core Capabilities

🧠 Episodic Memory

🌙 Dream Processing

🔮 Belief Graph

⚗️ Neurochemistry

🪪 Entity Hatching

🔌 Skills & Routing

⚡ Token Optimization

🧬 Cognitive State

📋 Task Orchestration

🏗️ Memory Architect

🔗 Predictive Memory

🔑 Anthropic Direct