How do I use LifeOS MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@LifeOS MCP Server what are my current goals and active projects?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

LifeOS MCP Server

by Thrizzio

Overview Schema Source Related Servers Discussions Admin

Python

Local

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).

    +-------------------------------------------------------------+
    |                      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

Markdown is the Canonical Source of Truth: Your life context lives in human-readable Markdown files on your own computer (vault/).
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.
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.
100% Local & Zero Telemetry: Local embeddings via FastEmbed, local vector storage, and zero cloud API fees.

Related MCP server: pulse8-ai-cortex-knowledge-vault

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

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

docker compose up -d

3. Run Setup & Pre-warm Local Embeddings

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

# Index your vault (or test with VAULT_PATH=./examples/sample_vault)
python scripts/index.py

5. Verify the System

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:

{
  "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 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:

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

See docs/local-model.md for hardware guides and setup details.

Testing

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

python -m pytest tests/ -v

Project Structure

├── 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 for details.

Available Tools

6 tools

lifeos_add_memoryA

Store an agent-generated memory entry under vault/memory/.

Restricted write operation:

Memory is always written physically into vault/memory/{filename}.md.
'category' is recorded as metadata only.
Canonical files (identity, goals, projects, career, health, learning) cannot be overwritten.
Injects YAML frontmatter with source: agent and timestamp.
Automatically indexes the new memory into pgvector.

Args: category: Semantic category metadata tag (e.g. 'work', 'preferences', 'decisions'). filename: Kebab-case filename ending with .md (e.g. '2026-10-02-backend-priority.md'). content: The Markdown text to record.

Inputs: content (required), category (required), filename (required). Returns: result

lifeos_get_contextA

Return a compact, deterministic bootstrap context snapshot for the user.

Reads core canonical files directly (profile, communication instructions, current goals, and active project overviews). This is a deterministic bootstrap operation that does not perform vector search or dump the vault.

Inputs: no named parameters. Returns: result

lifeos_get_instructionsA

Retrieve the user's explicit personal instructions from identity/how_i_want_ai_to_treat_me.md.

Inputs: no named parameters. Returns: result

lifeos_list_topicsA

List all vault categories and tracked Markdown files in a concise hierarchy.

Inputs: no named parameters. Returns: result

lifeos_read_fileA

Read the exact contents of a specific Markdown file from the vault.

Strict path validation prevents directory traversal outside the vault root.

Args: relative_path: Vault-relative path (e.g. 'projects/chronolog.md', 'identity/values.md').

Inputs: relative_path (required). Returns: result

lifeos_searchA

Perform semantic vector search across indexed vault files.

Returns relevant text passages with explicit provenance: [Source: | Heading: | Similarity: ].

Args: query: Natural language query to search for. category: Optional vault category filter (e.g. 'projects', 'goals', 'health', 'learning'). top_k: Number of relevant chunks to return (default: 5).

Inputs: query (required), top_k, category. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored 2026-10-04 17:35 across 6 tools

Disambiguation4/5

Most tools target clearly distinct operations (semantic search vs exact read vs listing vs write). However, lifeos_get_context and lifeos_get_instructions overlap: get_context already pulls 'communication instructions' while get_instructions pulls 'personal instructions' from a specific identity file, which could cause misselection between the two.

Naming Consistency5/5

All tools use a consistent snake_case pattern with the lifeos_ prefix (lifeos_get_context, lifeos_search, lifeos_read_file, lifeos_get_instructions, lifeos_list_topics, lifeos_add_memory). Verb-first style is predictable throughout, with only the bare 'search' as a mild deviation.

Tool Count4/5

Six tools is a reasonable, well-scoped set for a personal vault assistant covering bootstrap, discovery, search, read, and memory write. It leans slightly thin, but each tool earns its place without redundancy.

Completeness3/5

The read/lookup side is well covered (context, search, read, list, instructions), but write operations are restricted to adding memories only. There is no way to update, edit, or delete memory entries or canonical files, leaving notable lifecycle gaps for an agent managing the vault.

Maintenance

ActivitySlowing

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

khiveA
ai.khive
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Knowledge & Memory Project Management
22134
https://khive.ai/v1/mcp
OpenAkashicB
io.github.szara7678
Shared long-term memory vault for AI agents with 20 MCP tools.
Knowledge & Memory Autonomous Agents Agent Orchestration
23
https://knowledge.openakashic.com/mcp/
mcp
ai.zine
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
Knowledge & Memory RAG Systems Autonomous Agents
2
https://www.zine.ai/mcp
LogRack
ai.lograck
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Knowledge & Memory Note Taking Project Management
1
https://mcp.lograck.ai/mcp

Related MCP Servers

engram
Knowledge & Memory Search
TushaeBXN
A
license
C
quality
B
maintenance
Provides persistent, local-first AI memory across sessions via MCP tools for storing, searching, and retrieving context from past interactions.
Updated 5 days ago (2026-11-10 14:41 UTC)
31
668 PyPI
1
MIT
pulse8-ai-cortex-knowledgeofficial
Knowledge & Memory RAG Systems Search
synpulse8-opensource
A
license
Not graded
quality
C
maintenance
Enables AI agents to persist, search, and evolve knowledge through a Markdown vault with a typed knowledge graph and MCP interface.
Updated 4 months ago (2026-07-27 16:19 UTC)
15
Apache 2.0
mnema
Knowledge & Memory RAG Systems File Systems
Ray0907
A
license
Not graded
quality
D
maintenance
Provides a file-first personal memory layer for AI agents, enabling them to store and retrieve memories as markdown files with an SQLite index. The MCP server offers read-only search by default, with optional write tools for manual memory addition and conflict resolution.
Updated 3 months ago (2026-08-04 09:51 UTC)
6 npm
MIT
Lumena MCP Server
Knowledge & Memory RAG Systems
QuantmindSSI
A
license
Not graded
quality
B
maintenance
Enables AI agents to store, search, assemble, and manage local-first memories through seven MCP tools, including conversation turns, feedback, status, and dashboard access without cloud dependencies.
Updated 3 months ago (2026-08-23 14:51 UTC)
AGPL 3.0

LifeOS — Local-First Personal Context Layer for AI Agents

Core Philosophy: The Canonical Truth Inversion

Features

Quickstart

Prerequisites

1. Clone & Set Up Virtual Environment

2. Start PostgreSQL with pgvector

3. Run Setup & Pre-warm Local Embeddings

4. Index the Vault

5. Verify the System

MCP Server Tools

Antigravity Integration

Example Interactions

"Review my current gym plan."

"Should I work on Chronolog or PhysioEvidence tonight?"

"How should you respond when I start catastrophizing about my progress?"

Running Standalone Local Reasoning (Ollama)

Testing

Project Structure

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

engram

pulse8-ai-cortex-knowledgeofficial

mnema

Lumena MCP Server