# LifeOS — Local-First Personal Context Layer for AI Agents

> **AI agents are powerful, but they have amnesia.**  
> Every new conversation starts with zero knowledge of the person they are helping. Users are forced to re-explain their background, their goals, their active projects, and how they want to be spoken to.  
> **LifeOS** solves this by providing a local-first personal context and memory layer that gives AI agents access to the user's canonical knowledge through the **Model Context Protocol (MCP)**.

```text
    +-------------------------------------------------------------+
    |                      AI Reasoning Layer                     |
    |       Google Antigravity Agent  OR  Local Open LLM (Ollama) |
    +-------------------------------------------------------------+
                                   ▲
                          JSON-RPC │ over stdio
                                   ▼
    +-------------------------------------------------------------+
    |                      LifeOS MCP Server                      |
    |  - lifeos_get_context()         - lifeos_search()           |
    |  - lifeos_read_file()           - lifeos_get_instructions() |
    |  - lifeos_list_topics()         - lifeos_add_memory()       |
    +-------------------------------------------------------------+
            │                                             │
      Path Validation                               Vector Search
            ▼                                             ▼
+───────────────────────────+                 +───────────────────────────+
│   Canonical Truth Store   │                 │   Derived Vector Index    │
│   Plain Markdown Files    │                 │   PostgreSQL + pgvector   │
│   vault/<category>/*.md   │                 │   chunks table (dim: 384) │
+───────────────────────────+                 +───────────────────────────+
            │                                             ▲
      Watchdog Events                                     │
            └───────────────▶ Vault Indexer ──────────────┘
                              FastEmbed (Local ONNX)
                              BAAI/bge-small-en-v1.5
```

---

## Core Philosophy: The Canonical Truth Inversion

1. **Markdown is the Canonical Source of Truth:** Your life context lives in human-readable Markdown files on your own computer (`vault/`).
2. **PostgreSQL + pgvector is a Disposable Derived Index:** The database exists solely to accelerate semantic vector search. If the database is deleted, the entire index is rebuilt from disk in seconds.
3. **Model Independence:** Your memory belongs to you, not an AI vendor. Switch reasoning engines from Antigravity to local Ollama (Llama 3.2, Mistral, Qwen) without changing your vault or database.
4. **100% Local & Zero Telemetry:** Local embeddings via FastEmbed, local vector storage, and zero cloud API fees.

---

## Features

- **MCP stdio Protocol Discipline:** Standard output (`stdout`) is strictly reserved for clean JSON-RPC traffic. All logs, diagnostics, and progress bars route to `stderr` or `lifeos.log`.
- **FastEmbed Local Embeddings:** High-performance local ONNX embeddings with `BAAI/bge-small-en-v1.5` generating 384-dimensional dense vectors with sub-20ms latency.
- **Deterministic Context Bootstrap (`lifeos_get_context`):** Instant orientation reading profile, current goals, and behavioral instructions without vector search overhead.
- **Semantic Retrieval with Explicit Provenance:** Every search hit cites its source document, heading, and similarity score (`[Source: projects/chronolog.md | Heading: Architecture]`).
- **Strict Vault Security:** Path traversal protection, category whitelisting, lowercase kebab-case naming enforcement, and symlink escape defenses.
- **Controlled Memory Partition (`vault/memory/`):** Agent-created memories are quarantined with YAML frontmatter metadata and cannot overwrite canonical user files.
- **Live Synchronization (`watchdog`):** Vault edits automatically update the derived vector index in the background with event debouncing.

---

## Quickstart

### Prerequisites
- Python 3.11+
- Docker & Docker Compose (or local PostgreSQL with `pgvector`)

### 1. Clone & Set Up Virtual Environment
```bash
git clone https://github.com/your-username/LifeOS-MCP-weekend-challenge.git
cd LifeOS-MCP-weekend-challenge

# Create venv and install dependencies
uv venv .venv
.\.venv\Scripts\activate      # Windows
# source .venv/bin/activate   # macOS / Linux
uv pip install -r requirements.txt
```

### 2. Start PostgreSQL with pgvector
```bash
docker compose up -d
```

### 3. Run Setup & Pre-warm Local Embeddings
```bash
python scripts/setup.py
```
*This verifies your environment, initializes database tables, downloads local embedding weights so the model is 100% offline, and verifies vault partitions.*

### 4. Index the Vault
```bash
# Index your vault (or test with VAULT_PATH=./examples/sample_vault)
python scripts/index.py
```

### 5. Verify the System
```bash
python scripts/verify.py
```

---

## MCP Server Tools

LifeOS exposes exactly 6 intentional, safe tools:

| Tool | Signature | Purpose |
| :--- | :--- | :--- |
| `lifeos_get_context` | `()` | Deterministic bootstrap snapshot: profile, goals, active projects, and communication boundaries. |
| `lifeos_search` | `(query: str, category: Optional[str] = None, top_k: int = 5)` | Semantic vector search with explicit provenance headers. |
| `lifeos_read_file` | `(relative_path: str)` | Read exact Markdown file contents after strict boundary validation. |
| `lifeos_get_instructions` | `()` | Fast direct read of `identity/how_i_want_ai_to_treat_me.md`. |
| `lifeos_list_topics` | `()` | Structured tree summary of all categories and tracked files. |
| `lifeos_add_memory` | `(category: str, filename: str, content: str)` | Controlled memory write quarantined to `vault/memory/` with agent metadata. |

---

## Antigravity Integration

Add LifeOS to your Antigravity MCP configuration:

```json
{
  "mcpServers": {
    "lifeos": {
      "command": "C:/DEV WORK/Hactoberfest 2026/LifeOS-MCP-weekend-challenge/.venv/Scripts/python.exe",
      "args": [
        "C:/DEV WORK/Hactoberfest 2026/LifeOS-MCP-weekend-challenge/lifeos/server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

Reload MCP servers in Antigravity. The agent will automatically call `lifeos_get_context` and `lifeos_search` when working with you. See [docs/antigravity.md](docs/antigravity.md) for full instructions.

---

## Example Interactions

### "Review my current gym plan."
*LifeOS retrieves `health/gym.md` and `health/routines.md`, providing feedback aligned with your PPL routine and shoulder mobility notes.*

### "Should I work on Chronolog or PhysioEvidence tonight?"
*LifeOS searches your goals and journal, citing `[Source: journal/2026-10-02.md]` to remind you that Chronolog is your sole primary portfolio priority for systems internships.*

### "How should you respond when I start catastrophizing about my progress?"
*LifeOS reads `identity/how_i_want_ai_to_treat_me.md`, refuses empty cheerleading, checks actual git logs against `goals/current.md`, and gives you 1–3 concrete, high-leverage next actions.*

---

## Running Standalone Local Reasoning (Ollama)

Ensure Ollama is running (`ollama serve`) with `llama3.2`:

```bash
python -m lifeos.local_model "Based on my current goals, what is my biggest technical priority?"
```

See [docs/local-model.md](docs/local-model.md) for hardware guides and setup details.

---

## Testing

Run the test suite (100% offline with zero cloud dependencies):

```bash
python -m pytest tests/ -v
```

---

## Project Structure

```text
├── ARCHITECTURE.md          # Living architectural specification
├── CONTEXT.md               # Domain vocabulary and concepts
├── LICENSE                  # MIT License
├── Makefile                 # Developer shortcuts
├── README.md                # Project documentation
├── docker-compose.yml       # Local PostgreSQL + pgvector container
├── pyproject.toml           # Packaging configuration
├── requirements.txt         # Pinned project dependencies
│
├── vault/                   # User's private Markdown vault (gitignored)
│   └── <category>/.gitkeep  # Preserved directory structure
│
├── examples/
│   ├── antigravity/         # Antigravity MCP config and agent instructions
│   └── sample_vault/        # Committed synthetic demo vault
│
├── lifeos/                  # Core Python package
│   ├── config.py            # Settings and environment validation
│   ├── models.py            # Pydantic data schemas
│   ├── vault.py             # Path security and vault manager
│   ├── chunker.py           # Markdown section parser & hashing
│   ├── embeddings.py        # Local FastEmbed provider (384-dim)
│   ├── database.py          # PostgreSQL + pgvector client
│   ├── indexer.py           # Vault scanner and batch synchronizer
│   ├── retrieval.py         # Semantic search & provenance formatter
│   ├── memory.py            # Controlled agent memory writer
│   ├── watcher.py           # Real-time watchdog filesystem observer
│   ├── local_model.py       # Offline Ollama reasoning agent
│   └── server.py            # MCP Server over stdio
│
├── scripts/
│   ├── setup.py             # Setup and pre-warm script
│   ├── index.py             # CLI vault indexer
│   └── verify.py            # Diagnostic check script
│
├── tests/                   # Pytest automated test suite
└── docs/                    # Architectural and integration guides
    ├── adr/                 # Architecture Decision Records
    ├── antigravity.md       # Antigravity setup guide
    ├── architecture.md      # Deep-dive architecture notes
    ├── hackathon-submission.md # Pitch and demo scripts
    ├── local-model.md       # Local LLM guide
    ├── security.md          # Threat model and defenses
    └── vault-format.md      # Vault formatting specifications
```

---

## License

MIT License. See [LICENSE](LICENSE) for details.