# CogniRepo Configuration Reference

CogniRepo reads its configuration from `.cognirepo/config.json` in the project root.

---

## config.json Fields

```json
{
  "project_name": "my-project",
  "port": 8000,
  "storage": {
    "encrypt": false,
    "vector_backend": "faiss"
  },
  "models": {
    "enabled": true,
    "fast_model": "gemini-2.0-flash",
    "smart_model": "claude-opus-4-6"
  },
  "redis": {
    "enabled": false
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `project_name` | string | auto-detected | Human-readable project name |
| `port` | int | `8000` | REST API port |
| `storage.encrypt` | bool | `false` | Enable AES-256 encryption at rest |
| `storage.vector_backend` | string | `"faiss"` | Vector backend: `"faiss"` or `"chroma"` |
| `models.enabled` | bool | `true` | Enable multi-model routing |
| `models.fast_model` | string | `"gemini-2.0-flash"` | Model for fast/simple queries |
| `models.smart_model` | string | `"claude-opus-4-6"` | Model for complex reasoning |
| `redis.enabled` | bool | `false` | Enable Redis caching layer |

---

## Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `COGNIREPO_REDIS_URL` | Redis connection URL | `redis://localhost:6379` |
| `COGNIREPO_ENCRYPT_KEY` | Encryption key (overrides keychain) | `<hex-encoded AES key>` |
| `COGNIREPO_JWT_SECRET` | JWT signing secret for REST API | `<random hex 32 bytes>` |
| `COGNIREPO_PASSWORD_HASH` | Bcrypt hash of the API password | `$2b$12$...` |
| `ANTHROPIC_API_KEY` | Anthropic/Claude API key | `sk-ant-...` |
| `GEMINI_API_KEY` | Google Gemini API key | `AIza...` |
| `GOOGLE_API_KEY` | Gemini (alternate key name) | `AIza...` |
| `OPENAI_API_KEY` | OpenAI API key | `sk-...` |
| `GROK_API_KEY` | Grok API key | `...` |

---

## Storage Layout

```
.cognirepo/
  config.json           ← project settings (this file)
  vector_db/            ← FAISS index files
    index.faiss
    metadata.json
  graph/                ← knowledge graph
    graph.pkl
  index/                ← AST symbol index
    symbols.json
    reverse_index.json
    sha256_cache.json
  episodic/             ← event log
    events.jsonl
  sessions/             ← conversation session history
  errors/               ← error logs (date-stamped)
    2026-04-03.log
```

---

## Encryption at Rest

When `storage.encrypt: true`:

1. AES-256 GCM key is generated on first `cognirepo init`
2. Key is stored in the **OS keychain** (never written to disk)
3. All data in `vector_db/`, `graph/`, and `index/` is encrypted at rest
4. The `cryptography` package is required: `pip install cognirepo[security]`

**Keychain backends by platform:**
| Platform | Backend |
|----------|---------|
| macOS | Keychain Access (via `keyring`) |
| Linux | Secret Service (KWallet / GNOME Keyring) |
| Windows | Windows Credential Manager |

**To enable encryption:**
```bash
pip install cognirepo[security]
# Edit .cognirepo/config.json:
# "storage": { "encrypt": true }
cognirepo init  # re-run to generate and store the key
```

---

## Redis Cache

When `COGNIREPO_REDIS_URL` is set, CogniRepo uses Redis to cache:
- `retrieve_memory` results (keyed by `retrieve:{hash(query, top_k)}`)
- `lookup_symbol` results (keyed by `lookup_symbol:{name}`)

Cache TTL defaults to 300 seconds. The REST API gracefully degrades if Redis is unavailable.

```bash
export COGNIREPO_REDIS_URL=redis://localhost:6379
```

---

## MCP Server Configuration

### Claude Desktop (`.claude/CLAUDE.md`)
The `.claude/CLAUDE.md` file is auto-generated by `cognirepo init` and provides tool-first workflow instructions.

### Cursor (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "cognirepo-my-project": {
      "command": "python",
      "args": ["-m", "cognirepo", "serve", "--project-dir", "/path/to/project"]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)
```json
{
  "servers": {
    "cognirepo-my-project": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "cognirepo", "serve", "--project-dir", "/path/to/project"]
    }
  }
}
```

Run `cognirepo init` to auto-generate these files.

---

## Systemd Auto-restart (Linux)

CogniRepo can write a systemd user unit file:
```bash
cognirepo init  # answer "y" to systemd prompt
# or
systemctl --user enable ~/.config/systemd/user/cognirepo-watcher.service
systemctl --user start cognirepo-watcher
```

To check watcher status:
```bash
systemctl --user status cognirepo-watcher
cognirepo doctor  # shows heartbeat age
```
