# AI Workspace

> **Decommissioned:** this repository is no longer the active AIWorkspace runtime.
> Active services now run from `/Users/david/Developer/ai-workspace`, and Fidelity
> context lives in `/Users/david/Developer/fidelity-ai-context`. See
> [`DECOMMISSIONED.md`](DECOMMISSIONED.md) before using this repo.

AI Workspace is a local, profile-based companion workspace for AI-assisted professional work. It keeps project memory, raw evidence, local services, and AI client integrations organized so agents can work from current, auditable context instead of chat history alone.

The first real profile in this repository is `fidelity`, but the reusable model is intentionally project-independent.

## What This Repo Is

Use this repository beside your real implementation work to:

- maintain human-readable project memory;
- capture communication or screenshot evidence before curation;
- generate standups, stakeholder updates, and AI-to-AI prompts;
- expose bounded local context to AI clients through MCP;
- manage local services such as capture tools, context servers, and inbox helpers;
- support long-running AI workflows with durable state artifacts.

This repository is not the product codebase. It is a context and workflow layer.

## Architecture At A Glance

```text
Communication / photos / archives / manual notes
        ↓
Raw profile inbox evidence
        ↓
Human or agent curation
        ↓
Canonical Markdown project knowledge
        ↓
Derived local index
        ↓
Read-only MCP context server
        ↓
OpenCode / Claude Code / Copilot / Antigravity / other AI clients
```

Core principle:

```text
Markdown project knowledge is canonical. Inboxes, indexes, chat memory, and cloud memory are supporting layers.
```

## Main Folders

| Path | Purpose |
|---|---|
| `docs/` | Simple project-independent documentation for developers adopting the workspace |
| `core/` | Reusable operating model and architecture notes |
| `profiles/` | Project-specific configuration and assumptions |
| `workspaces/<profile>/project-knowledge/` | Profile-owned canonical Markdown vault |
| `agent-memory/` | Agent behavior, promotion, verification, and workflow memory |
| `workspaces/<profile>/inbox/` | Profile-owned raw evidence before promotion into canonical memory |
| `scripts/aiw/` | Service manager and local indexer |
| `scripts/mcp/` | MCP servers exposing bounded local context |
| `scripts/memory/` | Project-agnostic interface for canonical memory operations |
| `scripts/obsidian/` | Current Obsidian adapter |
| `scripts/mattermost-proxy/` | Mattermost proxy mirror connector for local evidence capture |
| `scripts/iphone-photo-inbox/` | Local photo inbox receiver |
| `apps/mac/AIWorkspace/` | macOS menu bar app for service visibility and control |

## Quick Start

Run basic checks for the active profile:

```bash
python3 scripts/aiw/services.py doctor --profile fidelity
python3 scripts/aiw/services.py status --profile fidelity
python3 scripts/aiw/indexer.py build --profile fidelity
```

Start the read-only context MCP server:

```bash
python3 scripts/aiw/services.py start aiw-context-mcp --profile fidelity
```

HTTP endpoint:

```text
http://127.0.0.1:8765/mcp
```

Health endpoint:

```text
http://127.0.0.1:8765/health
```

## Documentation

Start here:

- [Getting Started](docs/getting-started.md)
- [Architecture](docs/architecture.md)
- [Profiles](docs/profiles.md)
- [Memory Model](docs/memory-model.md)
- [MCP](docs/mcp.md)
- [Services](docs/services.md)
- [Local RAG Index](docs/local-rag-index.md)
- [Security and Privacy](docs/security-and-privacy.md)

Profile-specific project knowledge starts at:

- `workspaces/fidelity/project-knowledge/00-start/start-here.md` for the current Fidelity vault
- `profiles/fidelity/profile.md` for the Fidelity profile declaration
- `profiles/example/profile.md` for a sanitized reusable profile example

## Profiles

A profile represents one project, client, team, or workflow. It declares project assumptions, context sources, local services, and workflow defaults.

Current profiles:

```text
profiles/fidelity/
profiles/example/
```

Each profile resolves memory and inbox paths from `profiles/<profile>/workspace.json`. Fidelity data now lives under `workspaces/fidelity/`.

## Memory Model

The workspace separates memory by responsibility:

- `workspaces/<profile>/project-knowledge/`: canonical project facts for humans and AI;
- `workspaces/<profile>/inbox/`: raw evidence;
- `agent-memory/`: rules for how agents behave;
- `.aiw/indexes/`: derived local search indexes;
- external systems such as mem9: optional agent recall, not project truth.

Do not treat generated connector output or vector indexes as authoritative memory. Promote durable facts into the smallest correct Markdown file.

## MCP Model

`aiw-context-mcp` exposes profile-bounded, read-only context through MCP tools and resources. It does not capture traffic, send messages, or promote memory.

Current examples:

- `project_current_context`
- `project_search_memory`
- `memory_hybrid_search`
- `communication_latest`
- `communication_standup_context`
- `photos_latest`

## Service Manager

The service manager provides a single local lifecycle surface:

```bash
python3 scripts/aiw/services.py start --profile fidelity
python3 scripts/aiw/services.py stop --profile fidelity
python3 scripts/aiw/services.py status --profile fidelity --json
python3 scripts/aiw/services.py logs aiw-context-mcp --profile fidelity
```

Runtime logs, PID files, and state live under `.aiw/runtime/` and are ignored.

## Local Index

Build a derived search index over canonical Markdown:

```bash
python3 scripts/aiw/indexer.py build --profile fidelity
python3 scripts/aiw/indexer.py search "dismissal lifecycle" --profile fidelity
```

Indexes live under `.aiw/indexes/` and are ignored because they are rebuildable local artifacts.

## Security Defaults

- Keep secrets in ignored `.env` files.
- Do not commit raw tokens, cookies, session IDs, or captured headers.
- Keep MCP read-only by default.
- Treat inboxes and generated indexes as sensitive local artifacts.
- Use cloud memory systems only with an explicit data policy.

## Tests

```bash
python3 scripts/aiw/test_services.py
python3 scripts/aiw/test_profile.py
python3 scripts/aiw/test_indexer.py
python3 scripts/mcp/aiw-context-mcp/test_server.py
python3 scripts/iphone-photo-inbox/test_receiver.py
```

## Adoption Strategy

Recommended order for new projects:

1. Create an isolated profile:

   ```bash
   python3 scripts/aiw/profile.py create my-project --display-name "My Project"
   ```

2. Configure only the services the project needs.
3. Keep raw evidence outside canonical memory.
4. Build the local index.
5. Connect AI clients through MCP.
6. Promote durable facts into Markdown as work progresses.

Validate the profile layout with:

```bash
python3 scripts/aiw/profile.py doctor --profile my-project
```

The reusable core should not depend on a company name, ticket prefix, channel name, programming stack, or AI client.