# KusiScribe Core

> Local MCP Notary & Long-Context Fact Fabric for Autonomous Multi-Agent Workflows.

[English](README.md) | [Español](README.es.md)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python: 3.10+](https://img.shields.io/badge/Python-3.10%2B-brightgreen.svg)](https://www.python.org/)
[![Protocol: MCP](https://img.shields.io/badge/Protocol-MCP%20JSON--RPC%202.0-orange.svg)](https://modelcontextprotocol.io/)
[![Architecture: Single--Writer](https://img.shields.io/badge/Architecture-Single--Writer%20Deterministic-blueviolet.svg)](#architecture)

---

## Overview

Modern LLM agents operating in multi-turn, long-context software engineering environments suffer from two structural points of failure:

1. **The "Lost in the Middle" Attention Collapse:** When critical decisions, system rules, and technical architectures are placed in the middle or historical parts of an expansive context window, model retrieval fidelity drops sharply.
2. **Multi-Agent State Collision:** When multiple agents (e.g., Anthropic Claude, Google Antigravity, OpenCowork) execute in the same workspace, concurrent uncoordinated writes degrade memory files, causing hallucinations and race conditions.

**KusiScribe Core** solves both problems via an asynchronous, dual-layer forensic architecture:
* **The Single-Writer Principle:** An isolated notary engine captures raw agent dialogue streams, redacts secrets on the fly, and generates literal immutable transcripts. Memory distillation runs asynchronously through an atomic schema, ensuring knowledge bases are never corrupted by concurrent edits.
* **Deterministic MCP Access:** Exposes a 12-tool Model Context Protocol (MCP) server that provides agents with sub-500-token canonical memory cards, transversal topic indexes, playbooks, experiments, and literal grep search without fuzzy hallucinations.

---

## Empirical Benchmark: Attention Degradation vs. Structure

To evaluate the impact of information structure on agent recall across long contexts, an empirical benchmark of **$N = 450$ GPU inferences** ($3 \times 3 \times 50$ counterbalanced iterations) was conducted on local infrastructure (`EXP-2026-09-04-LOST-IN-MIDDLE`).

### Retrieval Matrix

| Structure Format | Top Position (Header) | Middle Position (Lost in Middle) | Bottom Position (Tail) |
| :--- | :---: | :---: | :---: |
| **Traditional Flat Text** | 100% | **2%** | **6%** |
| **Atomic Fact Block (60 words)** | **100%** | **72%** (30% entity binding) | **34%** |
| **Structured Matrix (`<table>` / Schema)** | **100%** | **100%** | **98%** |

### Architectural Implication
Unstructured prose and unbounded chat history lose up to 98% recall fidelity when pushed into the middle of context. KusiScribe converts raw dialogue into typed atomic facts (`- [TYPE | p:NN] Fact`) constrained to strict token limits (~500 tokens), completely bypassing the positional attention drop.

---

## Architecture

```text
+-------------------------------------------------------------+
|                     ACTIVE AGENT STREAMS                    |
|   Google Antigravity (Anty)  /  OpenCowork (Kairo / Claude)  |
+------------------------------+------------------------------+
                               |
                               | (stdout / transcript.jsonl)
                               v
                +------------------------------+
                |          watcher.py          |
                |   - Secret Masking (Regex)   |
                |   - Voice Topic Triggers     |
                |   - Transcript Archiving     |
                +--------------+---------------+
                               |
                 +-------------+-------------+
                 |                           |
                 v                           v
     +-----------------------+   +-----------------------+
     |  TRANSCRIPCIONES/     |   |   EXPEDIENTES/        |
     |  (Literal Work Logs)  |   |   (_indice_temas.json)|
     +-----------+-----------+   +-----------------------+
                 |
                 | Asynchronous Extraction (Triggered / Cron)
                 v
     +-----------------------+
     |  kusiscribe_distill   | <--- KusiAI Atomic Arbiter
     |  (Azure / OpenAI API) |      (Store / Skip / Update / Merge)
     +-----------+-----------+
                 |
                 v
     +-----------------------+
     |        FICHAS/        | <--- Single-Writer Authority
     |  (Atomic Memory Cards)|
     +-----------+-----------+
                 |
                 v
     +-------------------------------------------------------+
     |                     server_mcp.py                     |
     |         (Model Context Protocol JSON-RPC 2.0)         |
     +-------------------------------------------------------+
                 ^                           ^
                 |                           |
        Claude Desktop / Cursor     Antigravity / Terminals
```

---

## Features

### 1. Single-Writer Principle
* `watcher.py` is the **only process** permitted to write literal session records to `TRANSCRIPCIONES_LITERALES/`.
* `kusiscribe_distill.py` is the **only process** permitted to update knowledge base files in `FICHAS/`.
* The watcher never calls summarization APIs synchronously in the critical path, keeping latency at zero and eliminating file contention.

### 2. Zero-Leak Credential Masking
Before any line of conversation is flushed to disk, real-time regular expressions sanitize sensitive authorization data:
* OpenAI / Anthropic / HuggingFace tokens (`sk-...`, `Bearer ...`)
* GitHub Personal Access Tokens (`ghp-...`, `gho-...`)
* Slack & third-party webhook tokens (`xoxb-...`)
* Long cryptographic secrets and raw hashes

### 3. KusiAI 4-Way Conflict Arbitration
Memory distillation applies a 4-way decision matrix for incoming facts against existing records:
* `store`: Novel, valuable architectural decision or rule.
* `skip`: Redundant information already captured.
* `update`: Supercedes an older fact with higher priority.
* `merge`: Synthesizes complementary data into a unified bullet.

---

## The 12 Model Context Protocol (MCP) Tools

The included `server_mcp.py` implements the standard JSON-RPC 2.0 protocol over stdio, providing 12 specialized tools:

| Tool Name | Scope | Description |
| :--- | :--- | :--- |
| `ficha_leer` | Memory Cards | Reads the compact (~500 tokens) atomic memory card for a domain. |
| `tema_localizar` | Topic Map | Searches the cross-chat master index and returns chat UUIDs, lines, and dates. |
| `acta_buscar` | Forensic Grep | Fast literal search across all historical work logs and transcripts. |
| `expediente_leer` | Deep Archive | Reads comprehensive historical dossier files from `EXPEDIENTES/`. |
| `chats_listar` | Audit | Lists all tracked sessions and conversation UUIDs. |
| `chat_leer_completo` | Transcript | Returns the full literal session transcript for a specific UUID. |
| `experimento_leer` | Lab | Retrieves technical reports and benchmarks from `EXPERIMENTOS/`. |
| `experimentos_listar`| Lab | Lists all empirical benchmarks and research documents. |
| `playbook_leer` | Ops | Fetches step-by-step engineering SOPs from `PLAYBOOKS/`. |
| `playbooks_listar` | Ops | Lists all operational procedure manuals. |
| `script_leer` | Tooling | Reads source code of utility scripts stored in `SCRIPTS/`. |
| `scripts_listar` | Tooling | Lists available utility scripts and sanity checkers. |

---

## Quick Start

### 1. Clone & Install

```bash
git clone https://github.com/kusiai070/kusiscribe-core.git
cd kusiscribe-core
pip install -r requirements.txt
```

### 2. Configuration

Copy the template configuration:
```bash
cp config.example.json config.json
```

Edit `config.json` to define your monitored agent directories and model endpoint:
```json
{
  "fuentes": {
    "antigravity": {
      "activa": true,
      "directorio_brain": "~/.gemini/antigravity/brain"
    },
    "opencowork": {
      "activa": true,
      "directorio_brain": "~/AppData/Roaming/open-cowork/brain"
    }
  },
  "azure_foundry": {
    "endpoint": "https://<your-resource>.services.ai.azure.com/openai/v1/chat/completions",
    "model": "gpt-5.4-mini",
    "api_key": ""
  }
}
```

*Note: Environment variables `AZURE_AI_KEY` or `OPENAI_API_KEY` are automatically discovered if left empty in the configuration.*

### 3. Run the Notary Watcher

On Windows:
```cmd
arrancar_kusiscribe.bat
```

On Linux / macOS:
```bash
python3 watcher.py
```

### 4. CLI Inspection

Query historical facts directly from your terminal:
```bash
# Search across all logs
python buscar.py "deployment"

# Read atomic memory card for a domain
python buscar.py -f deploy

# Locate which sessions discussed a topic
python buscar.py -t vps
```

---

## MCP Client Setup

### Claude Desktop
Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kusiscribe": {
      "command": "python",
      "args": [
        "C:\\path\\to\\kusiscribe-core\\server_mcp.py"
      ]
    }
  }
}
```

### Cursor / Windsurf / Antigravity
Configure the server executable:
* **Command:** `python`
* **Arguments:** `["/absolute/path/to/kusiscribe-core/server_mcp.py"]`
* **Transport:** `stdio`

---

## Repository Structure

```text
kusiscribe-core/
├── EXPERIMENTOS/
│   ├── experimento_lost_in_the_middle.md   # 450 GPU inference benchmark
│   └── README.md
├── PLAYBOOKS/
│   ├── playbook_despliegue_produccion.md  # Sample SOP
│   └── README.md
├── SCRIPTS/
│   ├── saneamiento_fichas.py              # Health check & audit utility
│   └── README.md
├── examples/
│   ├── demo_transcript.jsonl              # Synthetic test transcript
│   └── README.md
├── arrancar_kusiscribe.bat                # Windows quickstart launcher
├── buscar.py                              # Forensic terminal CLI
├── config.example.json                    # Configuration template
├── kusiscribe_distill.py                  # KusiAI atomic memory distillation engine
├── requirements.txt                       # Python dependencies
├── server_mcp.py                          # 12-tool JSON-RPC 2.0 MCP server
├── watcher.py                             # Single-writer forensic notary daemon
├── .gitignore                             # Secret and data isolation rules
├── LICENSE                                # MIT License
└── README.md                              # Master documentation
```

---

## Security & Privacy Policy

KusiScribe Core is engineered for enterprise-grade privacy:
* All transcripts, index files, and memory cards are stored locally in plain markdown and JSON.
* The repository's default `.gitignore` prevents logs, state files, credentials, and transcript folders from ever being tracked in Git.
* No telemetry, no external callbacks, and no cloud dependencies beyond your own self-hosted or configured LLM endpoint.

---

## License

MIT License. Developed by [KusiAI](https://github.com/kusiai070). Free for personal, commercial, and research use.