david.delagneau/fidelity-ai-workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add comprehensive documentation for AI Workspace, including architecture, memory model, profiles, services, and security guidelines

Browse Source
This commit is contained in:
David Delagneau
2026-05-21 09:32:09 -06:00
parent e0069fd8c6
commit fb8a6ba2d9
9 changed files with 688 additions and 312 deletions
Download Patch File Download Diff File Expand all files Collapse all files

456
README.md
View File

@@ -1,368 +1,200 @@
# AI Workspace - Fidelity Profile # AI Workspace
Reusable AI-native companion workspace with Fidelity configured as the first real project profile. 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.
This repository is not the product codebase. It is an operational context layer used to keep project state current, capture communication evidence, prepare standups, draft clear stakeholder updates, and generate self-contained prompts for another AI that has access to the implementation codebase. The first real profile in this repository is `fidelity`, but the reusable model is intentionally project-independent.
The reusable logic lives in `core/`. The clean project second brain lives in `project-knowledge/`. Agent operating memory lives in `agent-memory/`. Fidelity-specific setup lives in the active profile under `profiles/fidelity/`. ## What This Repo Is
Shared cross-platform workflow/rule content lives in `.agents/`. OpenCode reads that content through `.opencode/` compatibility paths, and Gemini-compatible entry context starts at `GEMINI.md`. 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.
## Purpose This repository is not the product codebase. It is a context and workflow layer.
- Provide a reusable file-based AI workspace pattern ## Architecture At A Glance
- Keep Fidelity context current outside the main development machine
- Turn fragmented daily work into reusable AI-ready context
- Support standups, manager updates, Jira notes, and debugging summaries
- Generate high-quality prompts for GitHub Copilot or another AI on the Fidelity development machine
- Improve communication quality without losing technical accuracy
--- ```text
Communication / photos / archives / manual notes
## Operating Model ↓
Raw profile inbox evidence
You work on Fidelity from a different machine. ↓
Human or agent curation
This workspace is used to: ↓
Canonical Markdown project knowledge
- record what happened during implementation and debugging ↓
- sync relevant communication from Mattermost Derived local index
- preserve current project context between sessions ↓
- draft messages for the current manager or stakeholder with the right tone and scope Read-only MCP context server
- translate rough notes into concise native-sounding English ↓
- generate self-contained prompts for another AI that does have access to the product codebase OpenCode / Claude Code / Copilot / Antigravity / other AI clients
```
Core principle: Core principle:
Context must be updated before asking AI to write. ```text
Markdown project knowledge is canonical. Inboxes, indexes, chat memory, and cloud memory are supporting layers.
```
Reusable principle: ## Main Folders
Integrations extract evidence. The agent promotes memory. | 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
## Reusable Architecture Run basic checks for the active profile:
### /project-knowledge ```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
```
Canonical Obsidian second brain and transferable project knowledge. Start the read-only context MCP server:
- `00-start/` -> onboarding, glossary, and start-here ```bash
- `01-current/` -> current work and active work-item summary python3 scripts/aiw/services.py start aiw-context-mcp --profile fidelity
- `02-work-items/` -> ticket/task notes with metadata properties ```
- `03-context/` -> systems, workstreams, project-facing process, and iOS context
- `04-people/` -> people, roles, and collaboration context
- `05-decisions/` -> durable decisions
- `06-daily/` -> daily notes
- `07-maps/` -> graph hubs and semantic maps
- `08-bases/` -> Obsidian Bases
- `09-templates/` -> Obsidian templates
- `attachments/` -> vault assets
### /agent-memory HTTP endpoint:
Agent operating memory. ```text
http://127.0.0.1:8765/mcp
```
- `behavior/` -> agent learning and self-maintenance rules Health endpoint:
- `memory/` -> promotion, correction, and context-maintenance rules
- `integrations/` -> memory interface, Obsidian adapter, communication sources, and technical verification
- `workflows/` -> AI-to-AI prompting and workspace behavior model
- `maps/` -> agent-side navigation maps
### /.agents ```text
http://127.0.0.1:8765/health
```
Shared cross-platform workflow and rule source. ## Documentation
- `workflows/` -> reusable workflow definitions used by OpenCode-compatible commands and Antigravity-compatible workflow views Start here:
- `rules/` -> reusable skill/rule content
- `skills/` -> skill-path compatibility layer pointing at `rules/`
### /.opencode - [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)
OpenCode runtime surface. Profile-specific project knowledge starts at:
- `commands/` -> OpenCode slash commands, currently linked to `.agents/workflows/` - `project-knowledge/00-start/start-here.md` for the current Fidelity vault
- `skills/` -> OpenCode skills, currently linked to shared `.agents/` content - `profiles/fidelity/profile.md` for the Fidelity profile declaration
- `agents/` -> OpenCode agent definitions - `profiles/example/profile.md` for a sanitized reusable profile example
- `plugins/` -> OpenCode-specific plugins
### /core ## Profiles
Project-independent workspace logic. A profile represents one project, client, team, or workflow. It declares project assumptions, context sources, local services, and workflow defaults.
- `README.md` -> reusable operating model Current profiles:
- `memory/operational-memory.md` -> reusable memory classes, promotion rules, correction rules, self-maintenance rules
- `integrations/communication-model.md` -> live communication and historical archive connector contract
- `profiles/create-project-profile.md` -> checklist for adapting the workspace to another project
### /profiles ```text
profiles/fidelity/
profiles/example/
```
Project-specific configuration. 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.
- `profiles/fidelity/` -> active Fidelity implementation profile ## Memory Model
- `profiles/example/` -> non-sensitive example profile for new projects
Profiles declare project assumptions, communication sources, work-item system, stakeholders, enabled commands, and enabled skills. 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.
## Project Scope Do not treat generated connector output or vector indexes as authoritative memory. Promote durable facts into the smallest correct Markdown file.
Fidelity iOS ecosystem: ## MCP Model
- Fid4 `aiw-context-mcp` exposes profile-bounded, read-only context through MCP tools and resources. It does not capture traffic, send messages, or promote memory.
- XFlowSDK
- FTFrameworks
- REST migration replacing GraphQL over time
- Discourse and AO issues that require careful classification
--- Current examples:
## Runtime Structure - `project_current_context`
- `project_search_memory`
- `memory_hybrid_search`
- `communication_latest`
- `communication_standup_context`
- `photos_latest`
### /ai ## Service Manager
Runtime inbox for communication evidence. The service manager provides a single local lifecycle surface:
- `inbox/` -> communication evidence and transient inbox files before promotion into `project-knowledge/` ```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
```
### /prompts Runtime logs, PID files, and state live under `.aiw/runtime/` and are ignored.
Reusable prompts for: ## Local Index
- standups Build a derived search index over canonical Markdown:
- Mattermost updates
- manager communication
- issue clarification
### /workflows ```bash
python3 scripts/aiw/indexer.py build --profile fidelity
python3 scripts/aiw/indexer.py search "dismissal lifecycle" --profile fidelity
```
Repeatable working guides for: Indexes live under `.aiw/indexes/` and are ignored because they are rebuildable local artifacts.
- daily context sync ## Security Defaults
- flow debugging
- external issue analysis
### /scripts - 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.
Helpers for automation around memory access, context generation, communication drafting, and imports. ## Tests
- `scripts/aiw/` -> local AI Workspace service manager for profile services such as the Mattermost proxy mirror, Photo Inbox, and context MCP ```bash
- `scripts/mcp/` -> local MCP servers that expose bounded read-only workspace context to AI clients python3 scripts/aiw/test_services.py
- `scripts/memory/` -> project-agnostic interface for canonical memory python3 scripts/aiw/test_indexer.py
- `scripts/obsidian/` -> current Obsidian adapter and URI helpers python3 scripts/mcp/aiw-context-mcp/test_server.py
- `scripts/mattermost/` -> live communication connector python3 scripts/iphone-photo-inbox/test_receiver.py
- `scripts/slack/` -> historical archive importer ```
### /project-knowledge/.obsidian ## Adoption Strategy
Optional Obsidian vault configuration. Recommended order for new projects:
Open `project-knowledge/` as the Obsidian vault. Do not open the repository root as the vault. 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.
Portable vault configuration can be versioned, while local layout and plugin runtime files are ignored. The reusable core should not depend on a company name, ticket prefix, channel name, programming stack, or AI client.
Obsidian is the current visual interface over canonical memory. The reusable memory access layer is `scripts/memory/`, so the workspace can later swap Obsidian for another Markdown knowledge tool without changing the memory model.
---
## Daily Usage
### Start of day
Read:
- `project-knowledge/00-start/start-here.md`
- `project-knowledge/01-current/current-work.md`
- `project-knowledge/01-current/work-items.md`
- `project-knowledge/03-context/project.md`
- `project-knowledge/04-people/manager.md`
- `project-knowledge/04-people/index.md`
- latest file under `project-knowledge/06-daily/`
### During the day
Capture:
- implementation progress from the main development machine
- Mattermost conversations that change scope or priorities
- debugging findings
- open questions, blockers, and follow-ups
Write updates in:
- `project-knowledge/06-daily/YYYY-MM-DD.md`
### Before sending a message
Confirm:
- context
- current observation
- requested or implied action
- whether the issue is external behavior or regression
- whether the flow is authenticated or non-authenticated
### End of day
Update:
- today log
- current state
- next communication needs for the current manager or stakeholder
---
## Expected Output
This workspace should help produce:
- high-signal standups
- clearer Mattermost updates
- concise supervisor communication
- better issue framing
- more reliable AI-generated English
---
## OpenCode Entry Point
This workspace is designed to work well with the OpenCode VS Code extension.
Recommended usage:
1. Open this repository as its own VS Code workspace.
2. Start OpenCode from the integrated terminal at the repository root.
3. Begin each session with `/workspace-context` or the Fidelity alias `/fidelity-context`.
4. As new information appears during the day, update context before asking for drafting help.
Project commands live under `.opencode/commands/` and are intended to:
- load the reusable core plus active project profile
- sync live communication context into the workspace inbox
- draft standups
- draft manager updates
- draft prompts for another AI on the implementation machine
- force-refresh and inspect latest communication messages
- convert rough notes into daily log updates
This keeps AI output tied to the latest workspace state instead of relying on chat memory alone.
Cross-platform note:
- `.agents/` is the shared source of truth for reusable workflows/rules
- `.opencode/` is the OpenCode execution layer
- `.agent/` may exist as a naming alias for tools that look for singular agent directories
- `GEMINI.md` is the Gemini CLI entrypoint for shared workspace context
---
## Generic Commands
- `/workspace-context` -> load core plus active profile
- `/memory-health` -> check canonical memory and adapter health
- `/memory-create` -> create a typed canonical note through the memory interface
- `/communication-sync` -> sync live communication evidence and promote high-confidence memory
- `/archive-import` -> import historical archive evidence
- `/ai-prompt` -> generate a self-contained prompt for another AI
- `/standup` -> generate a work-item-aware daily standup
- `/manager-update` -> draft stakeholder-ready status
- `/translate` -> rewrite rough notes into professional English
- `/sync-context` -> incorporate new facts or corrections into memory
Compatibility aliases remain available for the Fidelity profile:
- `/fidelity-context`
- `/mattermost-sync`
- `/slack-import`
- `/copilot-prompt`
- `/swift-help`
---
## Communication Memory Flow
This workspace supports a live-memory pattern for communication sources such as Mattermost.
Recommended setup:
1. Use the workspace-local script at `scripts/mattermost/sync.sh`, or override it with `AIW_MATTERMOST_SYNC_CMD`.
2. Let OpenCode run with the project plugins enabled.
3. The Mattermost inbox plugin will periodically refresh `ai/inbox/mattermost-latest.md`.
4. Promote durable facts from the inbox into `project-knowledge/06-daily/`, `project-knowledge/01-current/`, `project-knowledge/02-work-items/`, and `project-knowledge/03-context/`.
Use `/communication-sync` or `/mattermost-sync` when you want to force a refresh manually.
Generic environment variables:
- `AIW_PROJECT_PROFILE`
- `AIW_CHANNEL_PREFIX`
- `AIW_MATTERMOST_SYNC_CMD`
- `AIW_MATTERMOST_SYNC_INTERVAL_MINUTES`
- `AIW_SLACK_EXPORT_PATH`
The `FIDELITY_*` variables remain supported as Fidelity-profile aliases, but new reusable setup should prefer `AIW_*`.
---
## Project Knowledge Vault
Open `project-knowledge/` as the Obsidian vault. The repository root remains the technical workspace for OpenCode, scripts, profiles, runtime inboxes, and generated evidence.
Recommended entry point:
- `project-knowledge/00-start/start-here.md`
- `project-knowledge/00-start/onboarding.md` for new members
- `project-knowledge/00-start/glossary.md` for terminology
- `project-knowledge/07-maps/` for graph hubs
Use Obsidian for:
- visual navigation
- graph/backlink review
- manual review of work items, people, decisions, and logs
- lightweight editing of the same Markdown memory files
Do not use Obsidian as a second memory database. The source of truth remains the versioned Markdown files under `project-knowledge/`.
Runtime/evidence stays outside the vault:
- `.opencode/`
- `scripts/`
- `core/`
- `profiles/`
- `ai/inbox/`
- `scripts/*/generated/`
Ignored Obsidian runtime files include workspace layout, plugin cache, snippets, and local plugin installs.
Project-agnostic memory helpers live under `scripts/memory/`:
- `scripts/memory/memory.sh create <type> <slug> [title]`
- `scripts/memory/memory.sh search <query> [folder]`
- `scripts/memory/memory.sh base-query <base-name> [format]`
- `scripts/memory/memory.sh health`
Obsidian adapter helpers live under `scripts/obsidian/`:
- `scripts/obsidian/cli.sh <obsidian-cli-command>`
- `scripts/obsidian/open.sh <vault-relative-path>`
- `scripts/obsidian/daily.sh`
- `scripts/obsidian/search.sh <query>`
- `scripts/obsidian/uri.sh <action> key=value`
---
## Creating Another Project
1. Copy `profiles/example/` to `profiles/<project>/`.
2. Fill in `profiles/<project>/profile.md`.
3. Set `AIW_PROJECT_PROFILE=<project>`.
4. Configure any communication connector with `AIW_*` variables.
5. Create or adapt `project-knowledge/` for the project-specific canonical memory.
6. Use `/workspace-context` to load the core plus active profile.
See `core/profiles/create-project-profile.md` for the full checklist.

68
docs/architecture.md Normal file
View File

@@ -0,0 +1,68 @@
# Architecture
AI Workspace is organized around explicit boundaries: profile configuration, raw evidence, canonical memory, derived retrieval, local services, and AI client adapters.
## System Flow
```text
Communication / screenshots / archives / manual notes
↓
Raw inbox evidence
↓
Agent or human curation
↓
Canonical Markdown project knowledge
↓
Derived local index
↓
Read-only MCP context server
↓
AI clients and agent workflows
```
## Responsibility Boundaries
| Layer | Responsibility | Canonical? |
|---|---|---|
| `core/` | Reusable architecture and operating model | yes, for workspace design |
| `profiles/<profile>/` | Project-specific configuration and assumptions | yes, for profile config |
| `project-knowledge/` | Human-readable project memory for the active profile | yes, for project facts |
| `ai/inbox/` | Raw evidence captured from connectors | no |
| `.aiw/indexes/` | Rebuildable search indexes | no |
| `.aiw/runtime/` | PID files, logs, local service state | no |
| `scripts/aiw/` | Profile-aware service/index utilities | code source |
| `scripts/mcp/` | MCP servers exposing local context | code source |
| `apps/` | Local UI surfaces such as the macOS menu bar app | code source |
## Current Repository Shape
The current repo still keeps the first real profile's vault at root-level `project-knowledge/`. That is acceptable during migration, but reusable code should increasingly resolve paths from profile configuration rather than hardcoding Fidelity-specific locations.
Target direction:
```text
profiles/<profile>/workspace.json # where profile data lives
workspaces/<profile>/project-knowledge/
workspaces/<profile>/inbox/
.aiw/indexes/<profile>/
```
## Design Principles
- Keep the smallest useful context loaded by default.
- Prefer just-in-time retrieval over dumping the entire workspace into prompts.
- Keep human-readable Markdown as the project source of truth.
- Keep raw evidence outside canonical memory until explicitly promoted.
- Keep profile-specific facts out of `core/` and generic scripts.
- Make local services observable through a single service manager.
- Treat cloud memory systems as optional, not authoritative.
## Why This Shape
Current AI workflow guidance emphasizes context engineering: the model should receive the smallest high-signal context needed for the task. This workspace supports that by combining:
- structured Markdown memory for durable facts;
- raw evidence stores for auditability;
- local indexes for retrieval;
- MCP tools/resources for AI clients;
- profile-specific boundaries for reuse across projects.

56
docs/getting-started.md Normal file
View File

@@ -0,0 +1,56 @@
# Getting Started
AI Workspace is a local, profile-based context system for AI-assisted work. It keeps project memory, raw evidence, local services, and AI client integrations organized without making any single AI tool the source of truth.
## Core Idea
Use the workspace as a companion repo beside your real project or client work:
```text
implementation repo / corporate tools / chat evidence
↓
AI Workspace inbox and memory curation
↓
human-readable project knowledge
↓
local index and MCP context server
↓
OpenCode / Claude Code / Copilot / other AI clients
```
## First Run
From the repository root:
```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
```
The `fidelity` profile is the first real project profile in this repo. New projects should follow the same shape but keep their own profile configuration and project memory isolated.
## Daily Use
1. Open the project knowledge vault in Obsidian or your Markdown editor.
2. Start only the local services needed for the profile.
3. Capture raw evidence into the profile inbox.
4. Promote useful, verified facts into canonical Markdown.
5. Let AI clients query context through MCP or direct file reads.
## Key Rules
- Canonical project memory is Markdown, not chat history or vector storage.
- Inboxes contain evidence, not promoted memory.
- Indexes are derived and rebuildable.
- MCP is read-only by default.
- Secrets belong in ignored local `.env` files.
## Next Reading
- [Architecture](architecture.md)
- [Profiles](profiles.md)
- [Memory Model](memory-model.md)
- [MCP](mcp.md)
- [Services](services.md)
- [Security and Privacy](security-and-privacy.md)

67
docs/local-rag-index.md Normal file
View File

@@ -0,0 +1,67 @@
# Local RAG Index
The local RAG index is the first retrieval layer over canonical Markdown memory.
## Purpose
It helps AI clients quickly find relevant snippets without loading the whole project knowledge vault into context.
```text
project-knowledge/ Markdown
↓
scripts/aiw/indexer.py
↓
.aiw/indexes/<profile>/project-knowledge.jsonl
↓
MCP tool: memory_hybrid_search
```
## Current Implementation
The current indexer is dependency-free and lexical. It is intentionally simple so it can run on a new machine without a vector database.
Build:
```bash
python3 scripts/aiw/indexer.py build --profile fidelity
```
Status:
```bash
python3 scripts/aiw/indexer.py status --profile fidelity
```
Search:
```bash
python3 scripts/aiw/indexer.py search "dismissal lifecycle" --profile fidelity
```
## What It Stores
- source path;
- heading;
- text chunk;
- mtime;
- content hash;
- chunk id.
## What It Does Not Do
- It does not replace Markdown.
- It does not write project facts.
- It does not index templates as real notes.
- It does not send data to a cloud service.
## Future Options
Future phases may add:
- better full-text ranking;
- semantic embeddings;
- Qdrant or Chroma as optional local vector stores;
- hybrid lexical + semantic search;
- index status in the menu bar app.
Keep this as a derived layer. The project knowledge vault remains canonical.

73
docs/mcp.md Normal file
View File

@@ -0,0 +1,73 @@
# MCP Integration
The Model Context Protocol (MCP) is the workspace's standard interface for exposing local context to AI clients.
## Role In AI Workspace
`aiw-context-mcp` is a read-only context server. It exposes bounded profile context through MCP tools and resources.
It should not:
- capture communication traffic;
- send messages;
- write canonical memory;
- promote facts automatically;
- expose secrets or raw credentials.
## MCP Concepts
MCP uses a host/client/server model:
- **Host**: the AI app, such as OpenCode, Claude Code, VS Code, Copilot, or another client.
- **Client**: the connection the host opens to a server.
- **Server**: a local or remote program that exposes context.
Servers expose primitives such as:
- **Tools**: callable functions.
- **Resources**: readable context objects.
- **Prompts**: reusable prompt templates.
AI Workspace currently focuses on tools and resources.
## Current Tools
Examples:
- `context_profiles`
- `project_current_context`
- `project_search_memory`
- `memory_hybrid_search`
- `communication_latest`
- `communication_date_context`
- `communication_standup_context`
- `photos_latest`
## Current Resources
Examples:
```text
aiw://profiles/fidelity/current-work
aiw://profiles/fidelity/work-items
aiw://profiles/fidelity/mattermost/latest
aiw://profiles/fidelity/photos/latest
```
## Security Posture
MCP tools can be model-controlled in many clients, so this workspace defaults to read-only context tools. If write tools are added later, they should require clear user intent, narrow scope, and audit-friendly outputs.
## Start The MCP Server
HTTP transport:
```bash
python3 scripts/aiw/services.py start aiw-context-mcp --profile fidelity
```
stdio transport:
```bash
python3 scripts/mcp/aiw-context-mcp/server.py --transport stdio
```

69
docs/memory-model.md Normal file
View File

@@ -0,0 +1,69 @@
# Memory Model
AI Workspace separates memory by purpose so that human-readable knowledge, raw evidence, agent behavior, and derived indexes do not collapse into one opaque store.
## Memory Layers
| Layer | Purpose | Examples | Canonical? |
|---|---|---|---|
| Canonical project memory | Durable project facts for humans and AI | current work, work items, people, decisions, daily notes | yes |
| Raw evidence | Captured data before curation | Mattermost mirror, photos, archives | no |
| Agent operating memory | Rules for agent behavior and workflows | promotion rules, communication style, verification rules | yes for agent behavior |
| Derived index | Fast retrieval over canonical memory | `.aiw/indexes/<profile>/` | no |
| External agent memory | Optional cross-agent recall | mem9, tool auto-memory | no for project truth |
## Canonical Markdown
The project knowledge vault should be readable without any AI tool:
```text
project-knowledge/
00-start/
01-current/
02-work-items/
03-context/
04-people/
05-decisions/
06-daily/
07-maps/
08-bases/
09-templates/
```
For future multi-profile setups, this same structure should live under a profile-specific workspace path.
## Evidence Promotion
Connectors write evidence. They do not decide what becomes memory.
Promotion flow:
```text
inbox evidence → verified fact → smallest correct Markdown file
```
Do not promote:
- secrets;
- sync status;
- generic chatter;
- unverified guesses;
- raw transcripts without curation.
## Local Index
The local RAG index is derived from canonical Markdown. It helps AI clients find relevant snippets quickly, but it is not the source of truth.
If index output conflicts with Markdown, Markdown wins.
## mem9 And Similar Memory Systems
mem9 can be useful as an optional cross-agent recall layer for preferences, reusable workflow habits, and non-sensitive operational memory. It should not replace the project knowledge vault.
Recommended stance:
```text
project-knowledge/ wins over mem9, vector stores, and chat memory.
```
For sensitive or corporate projects, avoid cloud memory ingestion unless the data policy is explicit and approved.

87
docs/profiles.md Normal file
View File

@@ -0,0 +1,87 @@
# Profiles
Profiles make the workspace reusable across projects, clients, or personal workflows.
Each profile should describe what the project is, where its memory lives, which communication sources matter, which local services are enabled, and how AI clients should access context.
## Current Profile Layout
```text
profiles/
fidelity/
profile.md
services.json
context-sources.json
example/
profile.md
```
## Recommended Future Layout
```text
profiles/<profile>/
profile.md # human-readable project profile
workspace.json # profile paths and defaults
services.json # local services for this profile
context-sources.json # communication/source filters
workspaces/<profile>/
project-knowledge/ # canonical Markdown vault
inbox/ # raw evidence for this profile
```
## Profile Files
### `profile.md`
Human-readable summary for agents and developers:
- project name;
- workspace role;
- communication sources;
- work-item system;
- stakeholders or roles;
- important domain themes;
- enabled workflows or skills.
### `workspace.json`
Planned path configuration. Initial versions can point to current paths:
```json
{
"profile": "example",
"display_name": "Example Project",
"knowledge_dir": "project-knowledge",
"inbox_dir": "ai/inbox",
"index_dir": ".aiw/indexes/example"
}
```
### `services.json`
Profile-specific local service manifest for `scripts/aiw/services.py`.
Examples:
- context MCP;
- communication proxy/mirror;
- photo inbox;
- future indexer or dashboard services.
### `context-sources.json`
Source filters for profile-bounded reads. For example, a Mattermost profile can define which channels count as high-signal context.
## Adding A New Project
1. Copy `profiles/example/` to `profiles/<new-project>/`.
2. Create or point to a project knowledge vault.
3. Define services only for integrations the project actually uses.
4. Put connector secrets in ignored `.env` files.
5. Build the local index.
6. Connect AI clients through the MCP server.
## Migration Rule
Reusable code should accept a `--profile` argument and resolve paths through profile configuration. Avoid adding new hardcoded references to Fidelity, channel names, ticket prefixes, or company-specific folders in generic scripts.

63
docs/security-and-privacy.md Normal file
View File

@@ -0,0 +1,63 @@
# Security And Privacy
AI Workspace is designed for local-first, auditable context management. Treat it as a companion workspace that may contain sensitive project metadata and communication evidence.
## Rules
- Do not commit secrets, tokens, cookies, API keys, headers, or session IDs.
- Keep connector credentials in ignored `.env` files.
- Keep raw evidence outside canonical project memory until curated.
- Keep MCP read-only unless a write tool has explicit safety rules.
- Treat generated indexes as local artifacts because they may contain snippets from project notes.
- Prefer local services for corporate or confidential projects.
## Ignored Local State
Examples of local-only data:
```text
.aiw/runtime/
.aiw/indexes/
ai/inbox/mattermost-mirror/
scripts/*/.env
```
## Cloud Memory Systems
Tools such as mem9 or managed vector stores can be useful, but they introduce a data boundary.
Before enabling them for a project, decide:
- what data may be stored;
- whether cloud storage is allowed;
- whether self-hosting is required;
- who can inspect/delete memories;
- what happens when cloud memory conflicts with Markdown.
Default recommendation:
```text
Use cloud memory only for non-sensitive preferences unless a project policy approves broader use.
```
## MCP Safety
MCP clients may let models invoke tools automatically. For that reason, workspace MCP tools should stay read-only by default and return bounded, source-attributed context.
If future MCP write tools are added, require:
- explicit user intent;
- narrow target paths;
- clear diffs or summaries;
- no secret exposure;
- easy audit through git.
## Sharing The Repo
Before sharing or open-sourcing a reusable version:
1. Remove or isolate project-specific profile data.
2. Confirm ignored inbox/runtime files are not tracked.
3. Replace real profile examples with sanitized examples.
4. Keep reusable architecture docs in `docs/` and `core/`.
5. Keep confidential project knowledge in private profile/workspace data.

61
docs/services.md Normal file
View File

@@ -0,0 +1,61 @@
# Services
The AI Workspace Service Manager provides one profile-aware lifecycle surface for local services.
## Responsibility
The service manager starts, stops, checks, and tails logs. It does not merge service responsibilities.
```text
Service Manager → process lifecycle/status/logs
MCP Server → read-only context access
Connectors → raw evidence capture
Agent/Human → memory promotion
```
## Common Commands
```bash
python3 scripts/aiw/services.py status --profile fidelity
python3 scripts/aiw/services.py status --profile fidelity --json
python3 scripts/aiw/services.py doctor --profile fidelity
python3 scripts/aiw/services.py start --profile fidelity
python3 scripts/aiw/services.py stop --profile fidelity
python3 scripts/aiw/services.py logs aiw-context-mcp --profile fidelity
```
## Service Manifest
Services are declared per profile:
```text
profiles/<profile>/services.json
```
A service can define:
- command;
- kind;
- groups;
- dependencies;
- restart policy;
- doctor checks;
- health checks.
## Current Service Types
- `process`: long-running command with PID/log tracking.
- `app-launcher`: one-shot command that opens an app/helper.
- `mcp`: process service exposing an MCP-compatible context server.
## Runtime Files
Runtime artifacts are local and ignored:
```text
.aiw/runtime/pids/
.aiw/runtime/logs/
.aiw/runtime/state/
```
These files are operational state, not project memory.