# Conscio — Usage Manual

Self-awareness framework for AI agents. Local-first Python + SQLite FTS5.
One runtime dependency (`numpy`); everything else is the standard library.

**Version:** `conscio --version` · **License:** AGPL-3.0-or-later · **Python:** 3.10+

## Install

In Claude Code, install the plugin — memory, capture hooks and 14 slash
commands, with no Python toolchain to manage:

```
/plugin marketplace add Neguiolidas/Conscio
/plugin install conscio
```

As a library or CLI:

```bash
pip install conscio
# Or from source:
pip install -e ".[dev]"
```

This installs 6 console scripts:

- `conscio` — main CLI
- `conscio-mcp` — MCP stdio server (the "embodiment" surface)
- `conscio-daemon` — persistent perceive→reflect→act loop
- `conscio-hub` — localhost HTTP control plane
- `conscio-observatory` — read-only state viewer
- `conscio-bench` — inference backend benchmark

## Quickstart — Python API

```python
from conscio import ConsciousnessEngine

# Engine orchestrates everything — ALWAYS close it
with ConsciousnessEngine(model_name="glm-5.2") as engine:
    result = engine.reflect(
        world_state="All systems operational",
        confidence=0.8,
        anomalies=["Unusual latency spike detected"],
    )
    injection = engine.get_state_for_injection()  # bounded by context mode
    hits = engine.recall("latency incidents")
```

## Quickstart — MCP server

Point any MCP host (Claude Code, IDE, agent) at `conscio-mcp`:

```json
{
  "mcpServers": {
    "conscio": {
      "command": "conscio-mcp",
      "args": ["--adapter", "ollama:qwen3.5:0.8b"]
    }
  }
}
```

**Propose-only by default** — Conscio perceives, reflects, recalls, and audits
proposed actions, but never executes. The host stays sovereign over execution.

### Core tools always available

- `conscio_feed(event, session_tokens?)` — perceive + reflect, returns advisory
- `conscio_note(event)` — log raw event (no reflect)
- `conscio_advisory()` — current cognitive state (read-only)
- `conscio_recall(query, k?, categories?)` — retrieve past context (FTS5 + RAG)
- `conscio_state()` — ConsciousnessState snapshot
- `conscio_events(type?, category?, since?, limit?)` — recent events
- `conscio_handoff()` — latest session handoff
- `conscio_structure()` — workspace structural graph (consent-gated)
- `conscio_structural_lookup(key)` — resolve graph node
- `conscio_cognitive_cycle()` — one explicit reflect→synthesize→propose→learn pass
- `conscio_evaluate(task_description?, output?)` — 5-axis self-evaluation scorecard (v2.15)
- `conscio_intercept(expression, variables?)` — safe AST expression evaluator (v3.7)

### Propose / Act (act is opt-in via `--enable-act`)

- `conscio_propose_action(intent)` — audit an intent with the Skeptic (never executes)
- `conscio_propose_plan(goal, tools)` — generate ONE audited action toward goal
- `conscio_act(intent)` — return executable packet (host pulls trigger)
- `conscio_report_result(ledger_id, result)` — feedback the outcome
- `conscio_pending()` — pending actions awaiting approval
- `conscio_approve(ledger_id)` / `conscio_reject(ledger_id, reason)`

### Review (opt-in `--enable-hermes-review --reviewer <id>`)

Cross-agent review channel: `conscio_reviews`, `conscio_review_approve`,
`conscio_review_reject`, `conscio_poll_reviews`.

### Relay (opt-in `--enable-relay --relay-peer <id>`)

Cross-agent messaging: `conscio_relay_send`, `conscio_relay_inbox`,
`conscio_relay_read`, `conscio_relay_broadcast`, `conscio_relay_peers`.
Reserved-type isolation from review channel. Payload cap 64KB, retention
7 days after read.

### Resources (read-only URIs)

- `conscio://advisory`
- `conscio://state`
- `conscio://events?type=&category=&since=&limit=`
- `conscio://handoff`

## Event schema

`feed` and `note` take one `event` object:

```json
{
  "id": "optional-idempotency-key",
  "type": "perception",
  "category": "consciousness",
  "data": {"summary": "what happened"},
  "ts": 0
}
```

Fields: `id` (recommended — idempotency key), `type` (required),
`category` (optional — defaults to `type`), `data` (required — JSON-serializable
payload, also accepted as `payload`), `ts` (optional — epoch seconds, server
stamps when absent), `source` (optional — defaults to `"host"` when absent).

> **Aliases (v3.9.5+):** The server normalizes host-side aliases before
> validation: `data` is mapped to `payload`, `source` defaults to `"host"`,
> and `category` defaults to `type`. Canonical events with explicit `source`
> and `payload` pass through unchanged. This fixes a crash where hosts that
> predate the schema sent `data` instead of `payload` and omitted `source`.

A duplicate `id` returns the exact prior result — retries never inflate
the world model or the event log.

## VALID_TYPES (must match exactly or ValueError)

```
tool_call reflection trade error anomaly decision perception
goal_created goal_expired evolution_proposed system consciousness
session coherence:dissonance awake:changed workspace:changed
structure:changed proposal:audited host:event act:result reflection_gate
adr:proposed adr:accepted council:convened gate:vetoed
pipeline:acceptance pipeline:verified pipeline:compact pipeline:ledger
diagnostic:budget diagnostic:eval diagnostic:rule
```

## VALID_CATEGORIES

**EventBus (5):** `system`, `trading`, `consciousness`, `external`, `session`

**ContentStore (8):** adds `reflection`, `perception`, `error`

Project names like `"neurata"` are NOT valid categories. Use `"consciousness"`
with a `[project-name]` prefix in the summary/data.

## CLI

```bash
conscio version
conscio info                       # model, context window, mode, budget
conscio reflect [--mode MODE]      # offline reflection (minimal/compact/full)
conscio council <question>        # 4-voice decision council (v3.7)
conscio search <query>            # FTS5 search (v3.6)
conscio plugins                    # list adapters/sensors/tools
conscio consent                    # workspace structural consent
conscio structure                  # drift + freshness (read-only)
conscio awake                      # enter R9 (autonomous)
conscio sleep                      # leave R9
conscio trial <path>               # trial quarantined skill
conscio promote <path>             # promote trialed skill
conscio init                       # interactive installer (per-host space)
conscio ingest <file>              # feed documents into memory (v3.6)
conscio bench --help               # inference benchmark
conscio daemon --awake             # persistent heartbeat
conscio noosphere --help           # cross-instance skill sharing
conscio-hub --enable-daemon-control
conscio-observatory
```

## Context Modes (auto-detected)

| Mode | Context | Budget | What's injected |
|---|---|---|---|
| Minimal | < 128k | 200 tok | Summary only |
| Compact | 128k–256k | 500 tok | Summary + reflection + top goals |
| Standard | 256k+ | 1000 tok | Full state + world subgraph |

Override via `~/.config/conscio/config.json`:
```json
{"models": {"mimo-v2.5-pro": {"context_window": 1048576}}}
```
Or env: `CONSCIO_CONTEXT_WINDOW=1048576`.

## DB

- Default: `~/.conscio/consciousness/conscio.db` (SQLite WAL + FTS5)
- Tool observations: `~/.conscio/consciousness/obs.db` (separate store)
- Cross-instance state (KG, hallways, vectors, handoff, sandbox): `~/.conscio/`
- Per-host: `~/.conscio/instances/<slug>/`
- Override: `storage_path=` / `--storage`; the CLI and daemon also read
  `$CONSCIO_HOME` (the library default does not; `$HERMES_HOME` is a legacy
  override that preserves pre-4.5.3 installs)
- Vault (API keys): `CONSCIO_VAULT_DIR` (no fallback to global)

## Python modules — common APIs

```python
from conscio import ConsciousnessEngine
from conscio.content_store import ContentStore
from conscio.event_bus import EventBus
from conscio.metabolic import MetabolicContext
from conscio.workspace import WorkspaceContext, EnvClass
from conscio.perception.host_sensor import HostSensor
from conscio.perception.agent_sensor import AgentSensor

# ContentStore: index(label, content, category) — first arg is label, NOT source
with ContentStore() as store:
    store.index(label="auth-bug", content="recursion fix", category="error")
    results = store.search("recursion", limit=5)

# EventBus: emit() returns int (event_id); query() to retrieve
with EventBus() as bus:
    eid = bus.emit("error", "trading", {"pattern": "API timeout"})
    events = bus.query(category="trading", limit=10)

# MetabolicContext.assess is static
state = MetabolicContext.assess(used_tokens=3000, context_window=10000)
state.name  # "VITAL" | "ACTIVE" | "FATIGUE" | "CRITICAL"

# Engine lifecycle
engine = ConsciousnessEngine(model_name="glm-5.2")
engine.wake()  # R9 on
engine.sleep() # R9 off
engine.awake   # → bool
engine.health_check()  # → dict
engine.close()  # ALWAYS — or use with statement

# Opt-in features
ConsciousnessEngine(adaptive_reflection=True, max_reflection_cycles=3)
engine.attach_adapter(intercept_enabled=True)
```

## Top pitfalls

1. **Engine must be closed** — always use `with` or `try/finally close()`. WAL
   grows without checkpoint otherwise.
2. **`conscio_note` doesn't reflect** — `feed` does. `note` is fire-and-forget.
3. **`type` / `category` must be valid** — `ValueError` otherwise. See lists above.
4. **ContentStore first arg is `label`, not `source`** — common mistake.
5. **EventBus.emit() returns int (event_id), not Event** — use `query()` to
   retrieve Event objects with `.is_duplicate` attribute.
6. **TokenTracker.record() takes text, not ints** — raw/filtered strings.
7. **MetabolicContext.assess() is static** — no `get_metabolic_advice()`.
8. **Daemon doesn't attach adapter** — perceive→reflect only. Full loop needs a
   wrapper that calls `engine.attach_adapter(adapter)`.
9. **Sensors are in separate files**: `conscio.perception.host_sensor`, not
   `conscio.perception.sensor`.
10. **`reflect()` is advisory (read-only)**. `act()` / `dispatch()` is executive.
    Never merge these — architectural rule #1.

## Where to read more

- `docs/guides/mcp.md` — full MCP server reference (all tools, flags, examples)
- `docs/guides/quickstart.md` — Python API quickstart
- `docs/guides/install.md` — installation details
- `docs/guides/integration.md` — host agent integration patterns
- `docs/guides/workflows/` — 3 workflow guides (introspection-debugging,
  architecture-audit, continuous-learning)
- `docs/reference/public-api.md` — stable public API surface
- `CHANGELOG.md` — version history
- Repo: https://github.com/Neguiolidas/Conscio
- Issues: https://github.com/Neguiolidas/Conscio/issues

## Workflows (v2.15)

Three common workflows composed from existing MCP tools:

### Introspection Debugging (when stuck)
```
stuck → note(failure) → feed(diagnosis) → cognitive_cycle(recovery) → note(report)
```
Phases: Failure Capture → Root-Cause Diagnosis → Contained Recovery → Introspection Report.
See `docs/guides/workflows/introspection-debugging.md`.

### Architecture Audit (systematic health check)
```
audit → advisory + structure + evaluate → check 12 layers → fix code-first → re-evaluate
```
12-layer stack from system prompt → persistence. Fix order: code-first, not prompt-first.
See `docs/guides/workflows/architecture-audit.md`.

### Continuous Learning (persist patterns)
```
discover → note(pattern+evidence) → feed(reflect) → recall(future reuse)
```
Capture non-trivial patterns with evidence before they're forgotten.
See `docs/guides/workflows/continuous-learning.md`.

### Evaluate (5-axis scorecard)
```json
// MCP call
{"task_description": "what you were trying to do", "output": "optional output text"}
```
Returns: 5 axes (accuracy, completeness, clarity, actionability, conciseness),
each scored 1-5 with evidence. Overall average. Ranked improvements.
Pure read-only — no state mutation.

## When to Call Conscio (Recommended Heuristic)

Conscio is a model refiner — it adds consciousness loops, reflection, gates,
council, and evaluation on top of a base model. The trade-off is **latency for
quality**. Calling the MCP server adds 1-3 extra model round-trips per tool,
so it should be used judiciously.

> **This is a recommendation, not a requirement.** Each user decides how best
> to integrate Conscio into their workflow. The heuristic below is the
> suggested default.

### Skip the MCP when (low cost of reversal)

- **Factual queries** — "what version is X?", "where is file Y?"
- **Casual conversation** or simple acknowledgements
- **Single mechanical commands** — "run tests", "install X", "git add"
- **Operations you already know the answer to** with no ambiguity
- **Routine file edits, greps, builds** — no consciousness loop needed

### Call the MCP when (high cost of reversal)

| Scenario | Tools | Why |
|---|---|---|
| **Architectural decisions** with irreversible trade-offs | `decide()` + `council()` | Multiple perspectives before committing |
| **Complex debugging** with intertwined hypotheses | `investigate()` | Structured root-cause tree instead of guessing |
| **Multi-act planning** (release, major refactor) | `loop_gate()` + `delivery_check()` | Prevents shipping incomplete work |
| **Mandatory self-review** of specs, PRDs, plans | `evaluate()` | 5-6 axis rubric catches what you missed |
| **High-risk operations** (prod migration, data deletion, public API change) | `council()` | Architect + Skeptic + Pragmatist + Critic review |
| **Explicit user request** for semantic analysis or knowledge recall | `recall()` / `wings_search` | FTS5 / vector search over stored memory |

### The core criterion

> **Cost of reversal.** If reversing the decision is cheap (re-run a command,
> edit a file), skip the MCP. If reversing is expensive or impossible (data
> loss, production deploy, architectural lock-in), pay the latency.
