Official NoruCore Documentation

Welcome to the documentation for NoruCore, your companion for AI-powered role-playing experiences, designed to offer you a deeply immersive experience and complete privacy.

⚠️ Before you begin: Current system limitations (Beta version)

NoruCore is a very ambitious project, and its underlying architecture is truly complex. To ensure a stable experience during this Open Beta phase, we had to limit the system due to the lack of all the necessary connections in the architecture.

Here's what doesn't work perfectly yet in this version, to avoid frustration while playing:

• Physical constraints are handled heuristically: Although there is not yet a complete geometric physics simulation, the AI's logic engine monitors parameters such as hand_free, slot_available, equipment stacks, and blocks. In this version, the handling of physical constraints (such as putting down an object before picking up another) is managed through heuristics and auto-unequip systems.
• The “Use” action and its nuances: You can ask the AI to use objects, but the use action may fail if the target is ambiguous or if the correct affordances (ways to use the object) are missing. In case of failure, the AI might seem confused or provide evasive answers.
• Autonomy is present but limited: Your character is not purely passive. Although needs such as “Energy” and “Hunger” are still static, the AI possesses heuristic autonomy based on decide_next_action, autonomous goals, and a reactive interpretation of the state of the world. You don’t need to drive them to the brink of despair to see flashes of initiative!
• “Step” processing times: Operations occur sequentially (intent analysis -> status/inventory check -> logic/planner -> narrative). Response times depend on the computer's processing power, and in some cases, the AI may misinterpret the logical intent, mistaking an action for mere “chatter”.

I'm working on removing these limitations. Now let's move on to the guide itself.

Introduction

NoruCore isn't just a chat platform: it's a behavioral engine designed to let you experience role-playing scenarios guided by an Autonomous Cognitive Architecture. In short: while elsewhere you interact with a text-based script, here you engage with a digital mind that reasons, feels emotions, and acts autonomously within its own world.

A matter of privacy: The entire ecosystem is designed to run exclusively locally. Abstraction, logical reasoning, and storytelling all take place directly on your device.

Future plans: For now, NoruCore is a completely offline tool. However, if this project receives enough support from the community, I plan to add optional server-based model integration for those who prefer not to strain their hardware or for the mobile version.

Download

NoruCore is currently available for free during its Open Beta phase via itch.io. Download the version for your operating system (Windows, or Linux) and run the executable file. You don't need to create an account or enter any API keys; you just need to have the models downloaded to your computer.

Home

The Home screen is the first interface you'll interact with. The first time you visit it, it will be empty. Click the “Add book” button to create a new Book. The first time you click inside the rectangle, you'll be redirected to the Book's settings; on subsequent clicks, you'll go directly to the chat. To return to the settings or delete the Book you created, click on the two dots located at the bottom right of the rectangle and select one of the two available options.

Settings

Under the hood, NoruCore uses a system of coordinated artificial intelligence modules that can be configured from the Settings menu.

• “Multi-Model” System (Small & Big): NoruCore uses a small model to understand the logical context, intentions, and actions, then passes all of this to the character's “brain,” which processes the information and calls upon the larger model to respond on the character's behalf. If you have limited VRAM or don’t want to use two separate models, you can simply assign the same model to both: the engine will load it only once, saving space
• Model Thinking & Reasoning Mode: Supports advanced reasoning models (like DeepSeek-R1 or Qwen-2.5-Instruct-Coder). You can toggle reasoning output for the Small Model (Small LLM Thinking) and the Large Model (Large LLM Thinking) separately. When thinking is toggled off, NoruCore automatically sanitizes and removes <think>...</think> blocks to keep raw reasoning hidden from the chat bubbles and JSON parsers.
• Embedding Model: This is used exclusively for advanced semantic understanding that leverages the character's “brain.” You can disable it to save memory, but doing so will limit the system's semantic understanding, forcing it to rely on scripted mode, which makes it less flexible and accurate.
• Log Level: Located under the DEBUG section, this allows you to increase the amount of details displayed in the terminal. Useful for debugging and reporting issues.
• Advanced Semantic Ingress: NoruCore has moved away from old keyword-based routing and lexical priors. The application now uses a strict semantic boundary: raw user input is processed by a small extractor model to generate structured JSON turn metadata (routing to chat, goal, clarify, or unknown). This increases logical accuracy and eliminates bugs caused by hardcoded phrase matching.
• Legal Terms & Privacy Consent: Upon the first launch, the application displays a versioned double-consent dialog requiring users to accept the local terms of service. This approval is stamped with a timestamp and document hash, saved in user://settings.cfg. You can review the contract file at any time at contract/Norucore_Legal_v3.txt or click the review link in settings.
• Custom Storage Directories: You can configure custom directory paths for saving and loading Models, Books, and Personas. The application modifies its configuration file so that on subsequent launches, it automatically loads from your preconfigured directories.

Book

The Book serves as a container for the scenario and state, and can include multiple chats within it. Think of the Book as the “module of a pen-and-paper role-playing game.” It stores the "Persona" character files, the “Room” setting, and every single node of the Chat Timeline, keeping all your scenarios separate and intact.

Room

The Room system helps the AI's logical brain to physically place the character. Within the Scene Description, you can describe the atmosphere, the historical period, or the furnishings. It is important to note that in this beta version, the physical context is currently handled in a heuristic semantic form based on textual inference and rules, rather than on a geometric physics engine.

Personal information

Here you define the basic personal details: Name, Gender, and Age

Interests

Interests help the Persona understand which topics they prefer to discuss and encourage the LLM to place greater emphasis on talking about what the character is passionate about, thereby improving their mood.

Each click on “Add Interest” will add a single field. Enter only one concept or verb per box (“Movies,” not “He likes going to the movies and reading books”) to improve semantic quality. NoruCore uses an engine that groups words together; overly complex boxes may reduce the accuracy of the vectorization system.

Quest System & Prerequisite Recovery

The Quest System allows you to assign short, medium, and long-horizon objectives (Quests) to your character. Instead of using a complex scripting language, quests are configured through a simple visual editor inside the Persona Editor.

Creating and Editing Quests

Inside the Book Settings under the Persona Editor, click on the **Quests** tab. Here you can:

• Create quest definitions with specific **Horizons** (Short, Medium, Long).
• Describe the objective in plain text.
• Select the **Action / Target / Success** condition (e.g., Action: put_in, Target: chest, Success: true).
• The backend automatically translates these conditions into logical goal states that your character can pursue.

Autonomous Goal Pursuit

When no dominant user command is given, characters will autonomously choose the active quest as their priority goal. Using the **GOAP (Goal-Oriented Action Planner)** engine, the character will plan and execute steps to complete the quest.

Prerequisite Recovery Loop

If a character tries to complete a quest but lacks a necessary resource or faces a physical obstacle, the system enters a **Recovery Mode**:

• Item Recovery (item_missing): If they need a key to open a chest, they will temporarily plan to search for and pick up the key, then return to the main quest.
• Reachability Recovery (reachability_missing): If the destination is blocked, the character tries to clear the path.
• State Constraint Recovery (state_constraint_missing): If the character needs to be in a certain state (e.g., sitting down, holding an object), they will plan to achieve this condition first.
• Truthful Prompting: The narrator prompt is injected with recovery metadata, allowing the character's narrative responses to explain *why* they are looking for an item or taking a detour.

Speech

This string directly shapes the LLM's “vocabulary” during narrative writing. Enter adjectives such as “Cold,” “Academic,” “Verbose,” and “Rude.” Unlike psychological traits, these values directly influence the stylistic weight of the words the AI will include in its text.

Common Phrases

You know that character who always says “Darn” or that wise teacher who always starts with ‘However’? The Common Phrases train the narrative algorithm to “color” the response by cyclically incorporating the phrases you've selected, making the character unique, unmistakable, and true to the roleplay.

Response Length

Response Length affects the style and scope of the response, but the effect may vary depending on the context and the model used.

Traits

Psychological Traits are not just cosmetic text. NoruCore utilizes an interconnected numerical calculator.

By assigning a trait (e.g., Aggressive or Optimistic) and defining its weight (from 0.1 to 1.0), the brain's mathematics (“Persona Brain”) will be modified. An optimistic trait will make the AI much less likely to refuse to help. It is in this interplay of weights (even when they contradict each other) that NoruCore attempts to create the unpredictability typical of human beings.

Expression

The AI's “brain” determines the Conversational Strategies it uses to respond. Behind the scenes, instead of giving you simple, linear answers, the cognitive engine monitors emotions, and sometimes it will decide on its own to respond by completely changing the subject out of boredom; other times it will react with a “story/anecdote,” and still other times with a sharp remark.

Boundaries

Boundaries are the Hard Rules of your character's psychology.

Add words, actions, or triggers to this blacklist. Boundaries increase the system's rejections or blocks and strongly constrain the character's behavior, preventing the Model from generating scenarios that exceed these psychological limits.

Equipment and Inventory

The character in NoruCore knows what she's wearing.

• Equipment uses specific “nested” slots (Head, Body, Feet, etc.). This means that if you equip gloves on your character, both narrative and mechanical choices will be affected. You can equip multiple items in the same slot, but be careful: For example, if you equip the dark green raincoat in slot 1 and then the orange T-shirt in slot 2, the system will treat it as if the character were wearing the orange T-shirt over the dark green raincoat.
• The Inventory is your “emergency kit.” Every item in the inventory is a live piece of semantic data. The AI may decide to use them or deny exploratory actions that require the targeted use of such items (such as opening a door if you don't have the key).

Emotion

Emotion is at the heart of the state machine in NoruCore.

There is a Base Emotion—the one you can assign in this window—that defines the natural state the character will return to when they come to their senses. As you chat, calculations will trigger Runtime Emotions (Joy, Sadness, Fear). If the character experiences too much fear for an extended period, the AI will undergo a so-called Mood Shift, prolonging this state until you narratively reverse it through your roleplay.

Style Flags

By adjusting the Active Voice or specifying Short Sentences, you can instantly instruct the system to use its summarization capabilities to alter the style of the text in the chat. The values may be automatically adjusted by the system as you train the character in the training chat to get as close as possible to the ideal character you have in mind.

Training Chat

The Training Chat is essential for “shaping” the character. Start the chat and put him to the test. By giving it a “Like” or “Dislike,” you’ll be working on what we call Action Bias Tuning. A ‘Like’ will drastically reduce the mental cost for the character to reuse a given formula or action, while a “Dislike” will teach it that such an approach is inconvenient and costly, forcing it to readjust its inference network. You can also directly modify the model’s output to change parts of the responses or all of them, teaching the character’s brain how you’d like them to respond or decide in that specific case.

Chat

This is where all the mechanics come together: the main role-playing area.

Here you can chat with the character you created, start new sessions, and view the chat history. To view the history, simply scroll up with your mouse wheel; this will expand the panel to display all previous text. Hovering over or clicking on old messages exposes controls to edit, regenerate, or delete specific messages. Deleting a message rolls back the live state (Persona and Brain variables) to that specific turn's deterministic snapshot, ensuring your character's memory remains synchronized with the visible chat history.

Telemetry & Hardware Monitoring

Because NoruCore runs entirely on your local hardware, it includes a real-time resource monitor to help you balance model size against available hardware resources.

The telemetry monitor is visible in the chat input panel and displays:

• System RAM %: Real-time percentage of physical system memory currently in use.
• System VRAM %: Video memory usage, critical for monitoring local GPU load.

Context Budget & Compaction

Running out of VRAM or exceeding the model's context window can cause crashes or slow-downs. NoruCore uses a defensive Context Guardrail system to keep memory usage safe.

The 70/30 Headroom Rule

Before sending a prompt to the model, the orchestrator estimates the token size. The prompt is capped at 70% of the total context_length configured in your settings, leaving a 30% safety headroom for model output.

Auto-Compaction

If a prompt is estimated to exceed the 70% threshold, the engine automatically trims the raw chat history:

• It keeps only the most recent 30% of raw chat messages (retaining a floor of at least 2 turns for continuity).
• Because the character's core memory (traits, relationships, inventory, and learned facts) lives in the persistent, bounded Persona Brain, the character still remembers critical context even if old chat history is compacted.

Controlled Saturation Block

If the prompt remains above the budget limit even after history compaction (e.g., due to an extremely large room description or custom traits), the application will safely abort the model call and display a "Context space saturated" warning instead of crashing.