fcontext 1.0.0__tar.gz

fcontext-1.0.0/PKG-INFO

@@ -0,0 +1,379 @@
+Metadata-Version: 2.4
+Name: fcontext
+Version: 1.0.0
+Summary: Context continuity across AI agents & sessions. Team knowledge collaboration. Industrial-grade AI delivery.
+License: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: markitdown
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+
+# fcontext
+
+**Context continuity across AI agents & sessions. Team knowledge collaboration. Industrial-grade AI delivery.**
+
+[![PyPI version](https://img.shields.io/pypi/v/fcontext?style=for-the-badge)](https://pypi.org/project/fcontext/)
+[![Python](https://img.shields.io/pypi/pyversions/fcontext?style=for-the-badge)](https://pypi.org/project/fcontext/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=for-the-badge)](LICENSE)
+[![Agents](https://img.shields.io/badge/agents-6%20supported-green?style=for-the-badge)](#supported-agents)
+
+---
+
+## The Problem
+
+AI coding agents are powerful, but they forget everything between sessions, lose all context when you switch agents, and have no way to share knowledge across a team. Every conversation starts from zero.
+
+```
+WITHOUT fcontext
+
+  Session 1 (Copilot): "Build the auth module"
+  Session 2 (Claude):  "What auth module? I don't see any context."
+  Session 3 (Cursor):  "Can you explain the project first?"
+  Teammate's Agent:    "I have no idea what your team has decided."
+
+  Result: Repeated explanations. Inconsistent output. Wasted tokens.
+```
+
+```
+WITH fcontext
+
+  Session 1 (Copilot): "Build the auth module" -> saves context
+  Session 2 (Claude):  Reads _README.md + _topics/ -> picks up work
+  Session 3 (Cursor):  Knows the full project, requirements, history
+  Teammate's Agent:    Imports experience pack -> instant onboarding
+
+  Result: Continuous context. Consistent quality. Industrial output.
+```
+
+---
+
+## Why fcontext
+
+### For Individuals
+
+> AI delivers results, but **you** deliver process and experience.
+
+Your expertise — how you approach problems, what patterns you've learned, what pitfalls to avoid — is lost every time a session ends. fcontext captures and persists that experience, so your AI gets smarter with every interaction.
+
+- **Cross-session memory** — Topics and conclusions survive between conversations
+- **Cross-agent portability** — Switch from Copilot to Claude to Cursor without losing context
+- **Experience visualization** — Your accumulated knowledge becomes a structured, reusable asset
+
+### For Teams & Enterprises
+
+> No single agent has all the context to do the job. Real work is distributed.
+
+In production environments, context is fragmented: requirements live in documents, domain knowledge lives in people's heads, architecture decisions live in past conversations. fcontext solves distributed context.
+
+- **Team knowledge sync** — Export/import experience packs so every team member's agent shares the same domain understanding
+- **Requirements traceability** — Track stories, tasks, bugs with full evolution history — from document to delivery
+- **Compliance-ready** — All data stored locally in `.fcontext/`, no cloud dependency, fully offline capable
+- **Industrial-grade delivery** — Structured context + requirements tracking + document indexing = consistent, auditable AI output
+
+---
+
+## Features
+
+| Capability | Description | Data Location |
+|------------|-------------|---------------|
+| **Multi-Agent Support** | Works with all mainstream AI coding agents | Agent-native config files |
+| **Document Indexing** | PDF, DOCX, XLSX, PPTX, Keynote, EPUB to Markdown | `.fcontext/_cache/` |
+| **Dynamic Context Building** | AI accumulates knowledge topics across sessions | `.fcontext/_topics/` |
+| **Experience Packs** | Import/export domain knowledge across projects and teams | `.fcontext/_experiences/` |
+| **Requirements Management** | Stories, tasks, bugs with evolution tracking | `.fcontext/_requirements/` |
+| **Workspace Map** | Auto-generated project structure overview | `.fcontext/_workspace.map` |
+| **Living Project Summary** | AI-maintained `_README.md`, first thing every session reads | `.fcontext/_README.md` |
+| **Offline & Secure** | All data local. No cloud. No API keys. No telemetry. | `.fcontext/` |
+
+### Supported Agents
+
+| Agent | Command | Config Format |
+|-------|---------|---------------|
+| GitHub Copilot | `fcontext enable copilot` | `.github/instructions/*.instructions.md` |
+| Claude Code | `fcontext enable claude` | `.claude/rules/*.md` |
+| Cursor | `fcontext enable cursor` | `.cursor/rules/*.md` |
+| Trae | `fcontext enable trae` | `.trae/rules/*.md` |
+| OpenCode | `fcontext enable opencode` | Uses Claude format |
+| OpenClaw | `fcontext enable openclaw` | `skills/` only |
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Python 3.9+
+- pip
+
+### Install from PyPI
+
+```bash
+pip install fcontext
+```
+
+### Verify
+
+```bash
+fcontext --version
+# fcontext 1.0.0
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialize in any project
+cd your-project
+fcontext init
+
+# 2. Activate your AI agent
+fcontext enable copilot    # or: claude, cursor, trae, opencode, openclaw
+
+# 3. Index your documents
+fcontext index docs/
+
+# 4. Check status
+fcontext status
+```
+
+That's it. Your AI agent now reads project context automatically on every session.
+
+---
+
+## Use Cases
+
+### Scenario 1: Picking Up Where You Left Off
+
+**Problem:** You had a deep debugging session yesterday. Today, a new session knows nothing.
+
+```bash
+# fcontext automatically persists session knowledge to _topics/
+# Next session reads _topics/ and _README.md first
+
+# To see what was saved:
+fcontext topic list
+fcontext topic show debugging-auth-flow
+```
+
+The new session starts with full context of yesterday's findings.
+
+### Scenario 2: Switching Between Agents
+
+**Problem:** You used Cursor for frontend work but need Claude for backend refactoring. Claude has no idea what Cursor did.
+
+```bash
+# Enable both agents — they share the same .fcontext/ data
+fcontext enable cursor
+fcontext enable claude
+
+# Both agents read the same _README.md, _topics/, _requirements/
+# Context is agent-agnostic
+```
+
+### Scenario 3: Onboarding a New Team Member
+
+**Problem:** A new developer joins. Their AI has zero project knowledge.
+
+```bash
+# Team lead exports accumulated knowledge
+fcontext export team-knowledge.zip
+
+# New member imports it
+fcontext experience import team-knowledge.zip
+
+# Their AI instantly knows: architecture, domain concepts, conventions, pitfalls
+fcontext experience list
+```
+
+### Scenario 4: Working with Binary Documents
+
+**Problem:** Product specs are in PDF/DOCX. AI cannot read them.
+
+```bash
+# Convert to Markdown so any agent can read them
+fcontext index specs/product-requirements.pdf
+fcontext index contracts/
+
+# AI now references the content directly from _cache/
+fcontext status
+```
+
+### Scenario 5: Requirements-Driven Development
+
+**Problem:** Requirements are scattered across documents, Slack, and meetings. AI builds the wrong thing.
+
+```bash
+# Structure requirements in fcontext
+fcontext req add "User authentication via OAuth" -t story
+fcontext req add "Support Google and GitHub providers" -t task --parent STORY-001
+fcontext req set TASK-001 status in-progress
+
+# AI reads _requirements/ and builds against tracked specs
+fcontext req board    # Kanban view
+fcontext req tree     # Hierarchy view
+```
+
+### Scenario 6: Sharing Domain Expertise Across Projects
+
+**Problem:** You've built deep domain knowledge in Project A. Project B needs the same expertise.
+
+```bash
+# In Project A: export to a git repo
+fcontext export git@github.com:team/domain-knowledge.git
+
+# In Project B: import as experience pack
+fcontext experience import git@github.com:team/domain-knowledge.git
+
+# Keep it updated
+fcontext experience update
+```
+
+---
+
+## Commands Reference
+
+### Core
+
+| Command | Description |
+|---------|-------------|
+| `fcontext init` | Initialize `.fcontext/` in workspace |
+| `fcontext enable <agent>` | Activate an AI agent |
+| `fcontext enable list` | Show all supported agents and status |
+| `fcontext status` | Show index statistics |
+| `fcontext clean` | Clear cached files |
+| `fcontext reset` | Delete all `.fcontext/` data |
+
+### File Indexing
+
+| Command | Description |
+|---------|-------------|
+| `fcontext index` | Scan and convert all files in workspace |
+| `fcontext index <file>` | Convert a specific file |
+| `fcontext index <dir>` | Convert all files in a directory |
+| `fcontext index -f` | Force re-convert even if up-to-date |
+
+### Requirements
+
+| Command | Description |
+|---------|-------------|
+| `fcontext req add "title" -t TYPE` | Add item (roadmap/epic/story/task/bug) |
+| `fcontext req list` | List all items (supports `--type`, `--status` filters) |
+| `fcontext req tree` | Hierarchy view |
+| `fcontext req board` | Kanban board by status |
+| `fcontext req show ID` | Item details + changelog |
+| `fcontext req set ID field value` | Update a field |
+| `fcontext req link ID TYPE TARGET` | Link items (supersedes/evolves/relates/blocks) |
+| `fcontext req trace ID` | Follow evolution chain |
+| `fcontext req comment ID "msg"` | Add a comment |
+
+### Topics
+
+| Command | Description |
+|---------|-------------|
+| `fcontext topic list` | List accumulated knowledge topics |
+| `fcontext topic show <name>` | Show topic content |
+| `fcontext topic clean` | Remove empty topic files |
+
+### Experience Packs
+
+| Command | Description |
+|---------|-------------|
+| `fcontext experience list` | Show imported packs |
+| `fcontext experience import <source>` | Import from zip, git URL, or download URL |
+| `fcontext experience remove <name>` | Remove a pack |
+| `fcontext experience update [name]` | Update from original source |
+| `fcontext export <output>` | Export knowledge to zip or git remote |
+
+---
+
+## How It Works
+
+```
+your-project/
+  .fcontext/                        # All context data (git-tracked)
+    _README.md                      # AI-maintained project summary
+    _workspace.map                  # Auto-generated structure
+    _index.json                     # File index registry
+    _cache/                         # Converted documents (Markdown)
+    _topics/                        # Session knowledge & conclusions
+    _requirements/                  # Stories, tasks, bugs
+      items.csv                     # Structured data
+      _backlog.md                   # Auto-generated summary
+      docs/                         # Per-item details
+    _experiences/                   # Imported domain knowledge (read-only)
+      <pack-name>/
+        _README.md
+        _cache/
+        _topics/
+
+  .github/instructions/             # Copilot (auto-generated by fcontext enable)
+  .claude/rules/                    # Claude (auto-generated)
+  .cursor/rules/                    # Cursor (auto-generated)
+  .trae/rules/                      # Trae (auto-generated)
+```
+
+Each AI agent gets instructions in **its native format**. The instructions teach the agent to:
+
+1. **Read** `.fcontext/_README.md` first to understand the project
+2. **Check** `_cache/` before trying to read binary files
+3. **Use** `fcontext req` commands for requirements (never parse CSV manually)
+4. **Save** important conclusions to `_topics/` for future sessions
+5. **Read** `_experiences/` for imported domain knowledge
+
+---
+
+## For Contributors
+
+We welcome contributions! Here's how to get started:
+
+```bash
+# 1. Fork and clone the repository
+git clone https://github.com/<your-fork>/fcontext.git
+cd fcontext
+
+# 2. Install in development mode
+pip install -e ".[test]"
+
+# 3. Run the test suite
+pytest tests/
+# 213 tests should pass
+
+# 4. Understand the structure
+# fcontext/
+#   cli.py              # CLI entry point & argument parsing
+#   init.py             # Workspace initialization & agent configs
+#   indexer.py          # File scanning, conversion, text copy
+#   experience.py       # Experience pack import/export/update
+#   requirements.py     # Requirements CRUD & reporting
+#   topics.py           # Topic management
+#   workspace_map.py    # Project structure generation
+
+# 5. Make your changes, add tests, verify
+pytest tests/ --tb=short
+
+# 6. Create a PR (never push directly to main)
+git checkout -b feat/your-feature
+git commit -m "feat: description"
+git push -u origin feat/your-feature
+```
+
+### Guidelines
+
+- Every new feature needs tests
+- Keep `from __future__ import annotations` in all modules (Python 3.9 compat)
+- CLI commands should give clear error messages when `.fcontext/` is not initialized
+- Experience packs under `_experiences/` are always read-only
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=anthropic/fcontext&type=Date)](https://star-history.com/#anthropic/fcontext&Date)
+
+---
+
+## License
+
+This project is licensed under the [Apache License 2.0](LICENSE).