Metadata-Version: 2.4
Name: focalpoint
Version: 0.4.0
Summary: FocalPoint — The attention manager for AI agents. Persistent memory, structured work tracking, proactive risk alerts, and bidirectional sync with GitHub/Notion.
Project-URL: Homepage, https://github.com/jeff0052/founderOSclaudecode
Project-URL: Repository, https://github.com/jeff0052/founderOSclaudecode
Author-email: Jeff <jeff@ontanetwork.com>
License: Business Source License 1.1
        
        License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
        "Business Source License" is a trademark of MariaDB Corporation Ab.
        
        Parameters
        
        Licensor:             Onta Network
        Licensed Work:        FPMS — Focal Point Memory System
                              Copyright (c) 2026 Onta Network
        Additional Use Grant: You may use the Licensed Work for any purpose,
                              including production use, EXCEPT for offering it as
                              a competing commercial memory/context management
                              service for AI agents.
        Change Date:          2030-03-22
        Change License:       Apache License, Version 2.0
        
        Terms
        
        The Licensor hereby grants you the right to copy, modify, create derivative
        works, redistribute, and make non-production use of the Licensed Work. The
        Licensor may make an Additional Use Grant, above, permitting limited
        production use.
        
        Effective on the Change Date, or the fourth anniversary of the first publicly
        available distribution of a specific version of the Licensed Work under this
        License, whichever comes first, the Licensor hereby grants you rights under
        the terms of the Change License, and the rights granted in the paragraph
        above terminate.
        
        If your use of the Licensed Work does not comply with the requirements
        currently in effect as described in this License, you must purchase a
        commercial license from the Licensor, its affiliated entities, or authorized
        resellers, or you must refrain from using the Licensed Work.
        
        All copies of the original and modified Licensed Work, and derivative works
        of the Licensed Work, are subject to this License. This License applies
        separately for each version of the Licensed Work and the Change Date may vary
        for each version of the Licensed Work released by Licensor.
        
        You must conspicuously display this License on each original or modified copy
        of the Licensed Work. If you receive the Licensed Work in original or
        modified form from a third party, the terms and conditions set forth in this
        License apply to your use of that work.
        
        Any use of the Licensed Work in violation of this License will automatically
        terminate your rights under this License for the current and all other
        versions of the Licensed Work.
        
        This License does not grant you any right in any trademark or logo of
        Licensor or its affiliates (provided that you may use a trademark or logo of
        Licensor as expressly required by this License).
        
        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
        AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
        EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
        TITLE.
License-File: LICENSE
Keywords: agent,ai,cognitive,context,mcp,memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# FocalPoint — AI Cognitive Operating System

**Memory + Attention Management + Workflow Orchestration.** FocalPoint gives your AI persistent memory, a workbench for task preparation, role-based thinking, and proactive risk alerts.

```bash
pip install focalpoint
```

## The Problem

AI agents forget everything between conversations. Existing memory tools (Mem0, Zep) store conversation snippets. But **remembering what was said is not the same as managing what needs to be done.**

## What FocalPoint Does

```
1. REMEMBER    — Structured memory across conversations (not just chat history)
2. PREPARE     — Workbench loads goal, knowledge, context, and subtasks before work
3. THINK       — Three roles (Strategy/Review/Execution) see different perspectives
4. REVIEW      — Three-Province protocol: parallel review before major decisions
5. ALERT       — Proactive heartbeat: "Task X is blocked for 3 days"
6. SEARCH      — Full-text search across titles, narratives, and knowledge docs
7. SYNC        — Bidirectional GitHub + Notion integration
```

## How It Compares

| Capability | Mem0 | Zep | Letta | CrewAI | Claude | **FocalPoint** |
|---|---|---|---|---|---|---|
| Persistent memory | Yes | Yes | Yes | Yes | Yes | **Yes** |
| Task lifecycle management | - | - | - | Partial | - | **Yes** |
| Dependency graph (DAG) | - | - | - | - | - | **Yes** |
| Proactive alerts | - | - | - | - | - | **Yes** |
| Knowledge docs + inheritance | - | - | - | - | Partial | **Yes** |
| Role-based context | - | - | - | Partial | - | **Yes** |
| Decision review workflow | - | - | - | - | - | **Yes** |
| Full-text search | Vector | Vector | Vector | - | - | **FTS5** |
| MCP native | - | - | - | - | Proprietary | **Yes** |
| Zero external deps | Partial | Partial | Yes | Yes | - | **Yes (SQLite only)** |

## Quick Start

### MCP Server (recommended)

```bash
pip install focalpoint
```

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "fpms": {
      "command": "focalpoint"
    }
  }
}
```

**OpenClaw**: Search `focalpoint-memory` in ClawHub and install.

23 tools are now available. Start a conversation and say `bootstrap`.

### Python API

```python
from fpms.spine import SpineEngine

engine = SpineEngine(db_path="./data/fpms.db")

# Cold start
bundle = engine.bootstrap()

# Create work items
engine.execute_tool("create_node", {
    "title": "Ship MVP", "node_type": "project", "is_root": True
})

# Prepare work context
workbench = engine.activate_workbench(node_id, role="execution")
# Returns: goal, knowledge, context, subtasks, suggested_next, role_prompt

# Proactive risk scan
alerts = engine.heartbeat()
```

## Work Mode

### Workbench — prepare before you work

```
You: "Work on the payment system task"
AI calls activate_workbench(node_id, role="execution")
-> Gets: goal, knowledge docs, context bundle, sorted subtasks,
   suggested next step, and execution role prompt
-> AI enters role, reads background, starts working
```

### Three Roles

| Role | Focus | Sees |
|------|-------|------|
| **Strategy** | Should we do this? Priority? | Decisions + feedback |
| **Review** | Any risks? Historical lessons? | Risk notes + progress |
| **Execution** | How to build it? | Technical details + progress |

### Three-Province Review

For major decisions: Strategy produces requirements -> Review + Engineer review in parallel -> Both approve or reject -> Max 3 rejections then escalate to human.

### Knowledge Documents

Attach design docs to nodes. Child tasks inherit parent knowledge automatically.

```
project "Payment System"
|-- overview.md        <- Project background
|-- architecture.md    <- Design docs
|
\-- task "Implement API"
    -> Inherits overview + architecture automatically
```

## Available Tools (23)

| Category | Tools |
|----------|-------|
| **Write (11)** | create_node, update_status, update_field, attach/detach_node, add/remove_dependency, append_log, unarchive, set_persistent, set_knowledge |
| **Read (5)** | get_node, search_nodes, get_knowledge, delete_knowledge, get_assembly_trace |
| **Cognitive (4)** | bootstrap, heartbeat, activate_workbench, get_context_bundle |
| **Review (1)** | sansei_review |
| **Runtime (1)** | shift_focus |

## Architecture

```
Brain (LLM)              Spine (FocalPoint engine)
  |                         |
  | -- Tool Call -->        | Validate -> Write SQLite -> Narrative -> Audit
  |                         |
  | <-- Context ---         | Assemble L0/L1/L2 -> Trim -> Inject prompt
```

**Brain** = LLM. Only reads context and issues Tool Calls.
**Spine** = Deterministic engine. All logic here. LLM never touches storage directly.

Storage: Pure SQLite. No vector DB, no Redis, no PostgreSQL.

## Stats

| Metric | Value |
|--------|-------|
| Tests | 667 |
| MCP Tools | 23 |
| External dependencies | 0 |
| Cold start | < 100ms |
| Supported LLMs | Any (via MCP) |

## Requirements

- Python 3.10+
- No external services — runs 100% locally on SQLite

## License

[Business Source License 1.1](LICENSE) — Free to use, modify, and deploy. Cannot be used to build a competing commercial memory service. Converts to Apache 2.0 on 2030-03-22.

## Links

- [PyPI](https://pypi.org/project/focalpoint/)
- [ClawHub](https://lobehub.com/skills/openclaw-skills-focalpoint-memory)
- [Product Introduction](docs/marketing/PRODUCT-INTRO.md)
- [Usage Guide](docs/marketing/USAGE-GUIDE.md)
- [Work Mode Guide](docs/WORK-MODE-GUIDE.md)
