scribe-llm 0.4.0__tar.gz

scribe_llm-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + dev deps
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check scribe tests
+
+      - name: Run tests
+        # Integration tests need a live llama-server / model downloads, which
+        # aren't available on CI runners — they run locally instead.
+        run: pytest -q -m "not integration"

scribe_llm-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+# Publishes the package whenever a GitHub Release is published.
+# Uses PyPI Trusted Publishing (OIDC) — no API token is stored in the repo.
+#
+# One-time setup on PyPI (https://pypi.org/manage/account/publishing/):
+#   Add a "pending publisher" for project `scribe-llm` with:
+#     Owner:           pedjaurosevic
+#     Repository:      scribe-ai
+#     Workflow name:   publish.yml
+#     Environment:     pypi
+# After the first successful run the project exists and the publisher is permanent.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write          # required for trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Verify metadata
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

scribe_llm-0.4.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Scribe local state & data (per-user, never commit)
+.scribe/
+scribe-workspace/
+*.lance/
+*.db
+
+# Editor / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Local config with real endpoints/keys
+config/config.toml

scribe_llm-0.4.0/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to Scribe are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-06-16
+
+A web release: a studio for writing books with your local model, and an open
+format for the knowledge Scribe distills.
+
+### Added
+- **Web Book Studio** (`scribe/templates/editor.html`, `scribe/documents.py`):
+  a dark, VSCode/Antigravity-style web UI with three resizable panes
+  (Explorer · Editor · Assistant). Books are a table of contents plus one
+  markdown file per chapter; the model drafts a TOC, then writes chapter by
+  chapter straight into the page. Exports to Markdown, EPUB (pandoc, one
+  section per chapter + title page) and PDF (browser print view).
+- **Integrated terminal** (`/ws/terminal`): a real login shell in a PTY bridged
+  to xterm.js, toggled with `Ctrl+\``, PIN-gated like the rest of the UI.
+- **Open Knowledge Format wiki**: `scribe wiki distill` now stores pages as OKF
+  markdown — YAML frontmatter (`type/title/description/tags/timestamp/source`),
+  `index.md` + `log.md`, inter-page links. `ensure_frontmatter` backfills a
+  valid block when the model omits one. SME/RAG are framed as derived indexes
+  over these files. See `docs/open-knowledge-format.md`.
+
+### Changed
+- The web UI now binds to **`127.0.0.1`** by default (was `0.0.0.0`); the
+  integrated shell terminal should not be network-reachable without an explicit
+  `--host 0.0.0.0` (which prints a warning).
+- PyPI distribution renamed `scribeai` → **`scribe-llm`** (import package and
+  CLI remain `scribe`).
+
+## [0.3.0] - 2026-06-13
+
+A synthesis release: the strongest mechanisms from sibling local-agent
+projects (Synap, Konok, ExoLab, CANYON) and Odysseus, folded into Scribe.
+
+### Added
+- **GBNF tool-call enforcement** (`scribe/grammar.py`): a grammar generated
+  from the tool schemas makes a malformed tool call grammatically impossible
+  on llama.cpp; `tool_grammar = "auto"` re-asks a fumbled call under the
+  grammar, `"force"` constrains every forced call.
+- **Reasoning gate** (`scribe/reasoning_gate.py`): `reasoning = "auto"` enables
+  server-side thinking only for prompts that benefit (code, debugging,
+  multi-step, long), bilingual EN/SR heuristic.
+- **Execution sandbox** (`scribe/tools/sandbox.py`): destructive-command gate,
+  Python AST gate, and a bubblewrap container (read-only root, writable
+  workspace, no network) with CPU/memory limits; degrades without bwrap.
+- **Git checkpoint/rollback** (`scribe/tools/checkpoint.py`): `workspace_checkpoint`
+  / `workspace_rollback` tools and a verify-then-roll-back loop; snapshots as
+  git tree objects that leave history untouched.
+- **Hybrid retrieval** (`scribe/memory/hybrid.py`): SQLite FTS5 lexical branch
+  fused with vector search via Reciprocal Rank Fusion. `rag search` is hybrid
+  by default; new `rag ask` (grounded Q&A) and `rag reindex`.
+- **Citation grounding** (`scribe/prompts.py`): numbered sources, mandatory
+  `[n]` citations, `[CONTRADICTION]` tagging, refusal outside the sources.
+- **SPI grounding metric** (`scribe/evolve/spi.py`) and **`scribe bench`**:
+  deterministic Source-Presence Index over a checksum-locked grounded suite.
+- **ORORO traces** (`scribe/trace.py`): append-only canonical-JSON event log
+  per session; `scribe trace`.
+- **Status contract** (`scribe/status.py`): machine-readable `scribe status --json`.
+- **Project vaults** (`scribe/vault.py`): `scribe init` for isolated per-project
+  RAG/SME stores.
+- **WorldModel** (`scribe/worldmodel.py`): a persona always injected into the
+  system prompt; `scribe remember`.
+- **Pulse & Diary** (`scribe/pulse.py`): heartbeat log and nightly reflection.
+- **Model discovery & blind compare** (`scribe/discovery.py`, `scribe/compare.py`):
+  `scribe discover` and `scribe compare`.
+
+### Changed
+- `LLMAdapter` gained `thinking_mode` and `tool_grammar`; `_with_thinking`
+  is now message-aware for the reasoning gate.
+- `verify_manifest` covers multiple held-out suite files.
+
+## [0.2.1] - 2026-06-09
+
+### Added
+- GitHub Actions CI: runs `ruff` lint and the unit `pytest` subset
+  (`-m "not integration"`) on Python 3.10 / 3.11 / 3.12 for every push and PR.
+- `integration` pytest marker for tests that need a live llama-server or model
+  downloads, so the unit suite stays fast and runnable anywhere.
+- `CONTRIBUTING.md` with the local dev / test workflow.
+- Status badges in the README.
+
+### Changed
+- Clarified the install steps in the README and landing page: `./scripts/install.sh`
+  already installs the package, so the extra `pip install -e .` is now shown only
+  as the manual alternative.
+
+### Fixed
+- Cleaned up the codebase so `ruff` passes on the full lint rule set
+  (import order, unused imports, f-strings, modern type hints) — no behavior change.
+- Declared previously-undeclared runtime dependencies that a clean install was
+  missing: `textual` (Textual UI import), and `pandas` + `pylance` (required by
+  the LanceDB-backed memory layer — without them `list_sources`/search silently
+  returned empty results).
+
+## [0.2.0] - 2026-06-08
+
+### Added
+- Initial public release.
+- Universal LLM adapter for any OpenAI-compatible (llama.cpp) endpoint.
+- Rich-based TUI with a streaming chat, plus an experimental Textual full-screen UI.
+- FastAPI web UI (`scribe web`).
+- Cross-session memory via the Semantic Memory Engine (SME).
+- RAG over a local document library (multilingual-e5 embeddings + LanceDB).
+- Modular skills: deep-research, writer, wiki-memory.
+- Sandboxed workspace file tools (read / write / list, scoped to the workspace).
+- Email bridge: send notifications and accept commands from one approved
+  address, using only the Python standard library.
+- Held-out fitness suite (`scribe evolve eval`).
+
+[Unreleased]: https://github.com/pedjaurosevic/scribe-ai/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/pedjaurosevic/scribe-ai/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/pedjaurosevic/scribe-ai/releases/tag/v0.2.0

scribe_llm-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to Scribe
+
+Thanks for your interest in improving Scribe. This is a small, focused project —
+the aim is a simple, dependable local-LLM agent, not a heavy framework.
+
+## Development setup
+
+```bash
+git clone https://github.com/pedjaurosevic/scribe-ai.git
+cd scribe-ai
+pip install -e ".[dev]"
+```
+
+This installs Scribe in editable mode together with the dev tools
+(`pytest`, `ruff`, `mypy`).
+
+## Running the checks
+
+```bash
+ruff check scribe tests          # lint
+pytest -q                        # full suite (incl. integration tests)
+pytest -q -m "not integration"   # unit subset — what CI runs
+```
+
+Tests are split into two groups:
+
+- **Unit tests** — fast, self-contained, no network. CI runs these
+  (`pytest -m "not integration"`) on Python 3.10, 3.11 and 3.12.
+- **Integration tests** (`@pytest.mark.integration`) — exercise the real
+  stack: the LLM adapter against a running llama-server, and the LanceDB
+  memory layer (which downloads an embedding model). Run them locally with a
+  server up; they're excluded from CI because runners have neither.
+
+## Pull requests
+
+- Keep changes small and focused; one logical change per PR.
+- Run `ruff check` and `pytest` before pushing — CI runs both.
+- Use English for code, identifiers, comments and commit messages.
+- Update `CHANGELOG.md` under `## [Unreleased]` when you add or change behavior.
+
+## Project layout
+
+```
+scribe/
+  cli.py            # Click entry point (the `scribe` command)
+  session.py        # session manager / cross-session continuity
+  llm_adapter.py    # OpenAI-compatible adapter for llama.cpp
+  memory/           # SME (semantic memory) + RAG
+  tools/            # sandboxed fs + shell tools
+  skills/           # modular skill loaders
+  ui/               # Rich theme, console, progress, logo
+  web.py            # FastAPI web UI
+  mail.py           # stdlib-only email bridge
+  evolve/           # held-out fitness evaluation
+tests/              # pytest suite
+docs/               # GitHub Pages landing page
+```
+
+## License
+
+By contributing you agree that your contributions are licensed under the MIT
+License, the same as the rest of the project.

scribe_llm-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Peterofovik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scribe_llm-0.4.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: scribe-llm
+Version: 0.4.0
+Summary: Universal TUI agent for autonomous research and writing, powered by llama.cpp
+Project-URL: Homepage, https://pedjaurosevic.github.io/scribe-ai/
+Project-URL: Repository, https://github.com/pedjaurosevic/scribe-ai
+Project-URL: Issues, https://github.com/pedjaurosevic/scribe-ai/issues
+Author-email: Pedja Urosevic <pedjaurosevic@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,autonomous,llama.cpp,llm,research,tui,writing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: lancedb>=0.4.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pylance>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: textual>=0.40.0
+Requires-Dist: toml>=0.10.0
+Requires-Dist: uvicorn>=0.23.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Scribe
+
+🌐 English · [简体中文](README.zh-CN.md)
+
+[![CI](https://github.com/pedjaurosevic/scribe-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/pedjaurosevic/scribe-ai/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+> Local-first chat + research + coding agent. Connects to **any** OpenAI-compatible server (llama.cpp, Ollama, LM Studio, or a cloud API key) and uses web search, RAG and semantic memory to research, write, and remember — across sessions. Runs comfortably on a 12 GB VRAM machine with Gemma 4 12B at 128k context.
+
+## Why Scribe
+
+Three properties that hold by construction, not by prompt-tuning:
+
+1. **The tool call cannot break.** On a llama.cpp server Scribe enforces tool
+   calls with a GBNF grammar generated from the tool schemas — a malformed
+   call is *grammatically impossible*, and a model that fumbles is re-asked
+   under the grammar. ([scribe/grammar.py](scribe/grammar.py))
+2. **Answers cite their sources, or say they can't.** Grounded Q&A maps every
+   claim to a numbered source `[n]`, tags `[CONTRADICTION]` when sources
+   disagree, and refuses to answer outside the sources. ([scribe/prompts.py](scribe/prompts.py))
+3. **Grounding is measured, not asserted.** `scribe bench` reports a
+   deterministic Source-Presence Index (SPI) over a checksum-locked held-out
+   suite — on Gemma 4 12B it scores **SPI 1.00**. ([scribe/evolve/spi.py](scribe/evolve/spi.py))
+
+> **Honest scope:** GBNF and constrained decoding aren't new — llama.cpp added
+> grammars in 2023, and the same idea ships elsewhere as "structured outputs".
+> Scribe's contribution is the *integration*: auto-generating the grammar from
+> your tool schemas and wiring it as an automatic tool-call safety net for small
+> local models. Guarantees 1–3 hold on llama.cpp; other backends degrade to a
+> best-effort text parser. The grammar guarantees a call's *form*, not the
+> model's *judgment* (it can still pick the wrong tool — it just can't emit a
+> malformed one).
+
+📖 Full overview on the [project site](https://pedjaurosevic.github.io/scribe-ai/).
+
+## Features
+
+- **Universal LLM Adapter** — llama.cpp, Ollama, LM Studio, or any OpenAI-compatible cloud API (OpenRouter, Groq, ...) — see [docs/providers.md](docs/providers.md)
+- **GBNF Tool Enforcement** — grammar-constrained tool calls on llama.cpp; auto-repair when a model emits a malformed call
+- **Grounded Q&A** — hybrid retrieval (FTS5 + vectors, RRF) with mandatory citations and contradiction tagging
+- **Quality Gate** — `scribe bench` runs a judge-scored fitness suite and the deterministic SPI grounding metric
+- **Safe Code Mode** — `/code` with a destructive-command gate, Python AST gate, bubblewrap sandbox, and git checkpoint/rollback
+- **Internet Research** — `web_search` + `web_fetch` tools; DuckDuckGo out of the box, Brave with a key
+- **Writing Agent** — deep-research and writer skills for books, papers and reports, with sandboxed workspace file tools
+- **Persistent Self** — a WorldModel persona injected into every prompt, plus pulse heartbeat and nightly diary
+- **Observability** — ORORO session traces and a machine-readable `scribe status --json` contract
+- **Project Vaults** — `scribe init` gives a directory its own isolated RAG/SME stores
+- **Model Discovery & Blind Compare** — auto-find local servers; A/B two models without bias
+- **Cross-Session Memory** — SME (Semantic Memory Engine) for seamless session continuity
+- **Email Bridge** — get results by email and send commands from one approved address (stdlib only)
+- **Wittgenstein + Peirce** — philosophy-inspired harness design for stable LLM behavior
+
+## Installation
+
+### From PyPI
+```bash
+pip install scribe-llm       # provides the `scribe` command
+```
+> The PyPI distribution is named `scribe-llm` (the import package and CLI stay `scribe`).
+
+### From source (🐧 Linux)
+```bash
+# Clone the repository
+git clone https://github.com/pedjaurosevic/scribe-ai.git
+cd scribe-ai
+
+# Run the install script: installs the package (editable), creates the
+# config, and scaffolds ~/scribe-workspace.
+./scripts/install.sh
+```
+
+### 🪟 Windows (WSL)
+Scribe runs seamlessly on Windows via **WSL (Windows Subsystem for Linux)**.
+1. Open your WSL terminal (e.g., Ubuntu).
+2. Run the Linux installation commands shown above.
+3. To configure Scribe to work with **Ollama** (either running natively on Windows or inside WSL), check out the [WSL & Ollama Integration Guide](docs/wsl_ollama_guide.md).
+
+---
+
+Or install by hand (skip the script):
+
+```bash
+pip install -e .
+```
+
+> Requires Python 3.10+. The install is editable, so `git pull` updates Scribe in place.
+
+## Quick Start
+
+1. Start your llama-server:
+```bash
+./scripts/start-server.sh
+```
+
+2. Start Scribe:
+```bash
+scribe chat
+```
+
+3. Scribe will automatically recall your last session and ask if you want to continue.
+
+## Configuration
+
+Edit `~/.config/scribe/config.toml`:
+
+```toml
+[scribe]
+base_url = "http://127.0.0.1:18083/v1"   # llama.cpp / Ollama / LM Studio / cloud
+model = "default"                         # auto-detects the loaded model
+api_key = "not-needed"                    # set a real key for cloud providers
+```
+
+Or use environment variables:
+
+```bash
+export SCRIBE_BASE_URL=http://localhost:11434/v1   # e.g. Ollama
+export SCRIBE_MODEL=gemma4:12b
+export SCRIBE_API_KEY=sk-...                       # cloud providers only
+```
+
+**Full provider guide** — llama.cpp, Ollama, LM Studio, OpenRouter/Groq, plus
+a recipe for **Gemma 4 12B with 128k context on a 12 GB GPU**:
+[docs/providers.md](docs/providers.md).
+
+**Web search** needs no setup (DuckDuckGo). For Brave Search, set
+`BRAVE_API_KEY` or `brave_api_key` under `[scribe]`.
+
+## CLI Commands
+
+```bash
+scribe chat                    # Interactive TUI chat (streaming by default)
+scribe chat --textual          # Full-screen Textual UI (experimental)
+scribe chat --resume TAG       # Resume a past session (no TAG = last one)
+scribe web                     # Web UI at http://localhost:8765
+
+scribe memory recall "query"  # Recall from semantic memory
+scribe rag search "query"     # Hybrid search (FTS5 + vectors); --semantic-only to opt out
+scribe rag ask "question"     # Grounded Q&A — answers cite sources or refuse
+scribe rag reindex             # Rebuild the lexical (FTS5) index
+scribe session last            # Show last session
+scribe session list            # List all sessions
+scribe session search "query" # Full-text search across all session transcripts
+
+scribe init [DIR]              # Create a project-local vault (config + ./.scribe)
+scribe discover [--tailscale]  # Find OpenAI-compatible model servers
+scribe compare "q" --a M1 --b M2  # Blind A/B two models on one prompt
+scribe bench [--fitness|--spi] # Quality gate: judge fitness + SPI grounding
+scribe trace [ID] [--json]     # Show a session's ORORO trace
+
+scribe pulse                   # Record one heartbeat (wire to a systemd timer)
+scribe diary                   # Reflect on today's sessions
+scribe remember "fact"        # Add a durable fact to the WorldModel
+
+scribe config show             # Show current config
+scribe status [--json]         # System status (--json = machine-readable contract)
+scribe evolve eval             # Run the held-out fitness suite (Phase 0)
+
+scribe mail send "Subj" "Body" # Email yourself a notification
+scribe mail watch              # Accept commands by email (see below)
+```
+
+## Email bridge
+
+Scribe can email you results and accept commands by email — using only the
+Python standard library (no extra dependencies).
+
+```toml
+[scribe.email]
+enabled = true
+address = "you@gmail.com"
+approved_sender = "you@gmail.com"   # the ONLY address allowed to command Scribe
+secret = "pick-a-token"             # must appear in command subjects
+```
+
+```bash
+export SCRIBE_EMAIL_PASSWORD="your-gmail-app-password"   # never in the config file
+
+scribe mail send "Done" "The report is ready."   # send a notification
+scribe mail watch                                 # poll inbox, run commands, reply
+```
+
+To run a command, email yourself with the secret in the subject:
+
+> **Subject:** `[scribe:pick-a-token] summarize the notes in research/`
+
+Scribe runs it with the **sandboxed workspace tools** (read/write/list files,
+no shell) and replies with the answer.
+
+**Security:** commands are accepted only when both the sender matches
+`approved_sender` **and** the subject carries `[scribe:secret]`. Since `From:`
+headers can be spoofed, the secret is the real gate — leave it empty to keep
+command intake off (sending still works). Gmail requires an
+[App Password](https://myaccount.google.com/apppasswords) (with 2-Step
+Verification enabled).
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│              SCRIBE TUI                  │
+│           (Rich-based interface)          │
+├─────────────────────────────────────────┤
+│              CORE KERNEL                 │
+│  Session Manager │ Skills │ Config       │
+├─────────────────────────────────────────┤
+│           LLM ADAPTER LAYER              │
+│    OpenAI-compatible (llama.cpp)         │
+├─────────────────────────────────────────┤
+│             MEMORY LAYER                 │
+│  SME (cross-session) │ RAG (documents)  │
+├─────────────────────────────────────────┤
+│              TOOLS LAYER                 │
+│   web_search │ web_fetch │ bash         │
+└─────────────────────────────────────────┘
+```
+
+## Philosophy
+
+Scribe is built on two philosophical pillars:
+
+1. **Wittgenstein** — Language games define meaning. Scribe uses explicit command vocabularies so the model knows exactly what each action means.
+
+2. **Peirce** — Signs gain meaning through interpretation chains. Scribe maintains semiotic continuity: every response becomes the next sign in the chain.
+
+## License
+
+MIT