fidelity-ai-workspace/README.md

AI Workspace

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

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:

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
project-knowledge/	Current canonical Markdown vault for the active Fidelity profile; future profiles should use explicit profile paths
agent-memory/	Agent behavior, promotion, verification, and workflow memory
ai/inbox/	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:

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:

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

HTTP endpoint:

http://127.0.0.1:8765/mcp

Health endpoint:

http://127.0.0.1:8765/health

Documentation

Start here:

• Getting Started
• Architecture
• Profiles
• Memory Model
• MCP
• Services
• Local RAG Index
• Security and Privacy

Profile-specific project knowledge starts at:

• 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:

profiles/fidelity/
profiles/example/

The current Fidelity profile still uses root-level project-knowledge/ and ai/inbox/ for compatibility. The target reusable shape is to resolve memory and inbox paths from profile configuration so future projects can keep isolated data under profile/workspace-specific directories.

Memory Model

The workspace separates memory by responsibility:

• project-knowledge/: canonical project facts for humans and AI;
• ai/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:

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:

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

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. Copy profiles/example/ to a new profile.
2. Create or point to a project knowledge vault.
3. Configure only the services the project needs.
4. Keep raw evidence outside canonical memory.
5. Build the local index.
6. Connect AI clients through MCP.
7. Promote durable facts into Markdown as work progresses.

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