201 lines
6.5 KiB
Markdown
201 lines
6.5 KiB
Markdown
# 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
|
|
|
|
```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 |
|
|
| `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:
|
|
|
|
```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:
|
|
|
|
- `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/
|
|
```
|
|
|
|
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:
|
|
|
|
```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_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.
|