Metadata-Version: 2.5
Name: devmcp-context
Version: 0.2.0
Summary: Structured AI memory layer - single source of truth for what your agent knows :)
Project-URL: Homepage, https://kushal1o1.github.io/devmcp-context/
Project-URL: Repository, https://github.com/kushal1o1/devmcp-context
Project-URL: Issues, https://github.com/kushal1o1/devmcp-context/issues
Project-URL: Documentation, https://kushal1o1.github.io/devmcp-context/
Author-email: Kushal <work.kusal@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Kushal
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,ai,claude,context,cursor,fastmcp,llm,markdown,mcp,memory,opencode,persistence
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: mcp[cli]<2.0.0,>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mkdocs-material>=9.0.0; extra == 'dev'
Requires-Dist: mkdocs>=1.5.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# devmcp-context

[![PyPI version](https://img.shields.io/pypi/v/devmcp-context.svg)](https://pypi.org/project/devmcp-context/)
[![Python](https://img.shields.io/pypi/pyversions/devmcp-context.svg)](https://pypi.org/project/devmcp-context/)
[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)

<p align="center">
	<img src="https://github.com/kushal1o1/devmcp-context/blob/main/static/logo.png?raw=true" alt="devmcp-context logo" width="420" />
</p>

Structured AI memory layer. A single source of truth for what your agent knows across conversations.

`devmcp-context` is a Model Context Protocol (MCP) server that provides persistent, organized memory for AI agents. Your agent's memory is now **visible, editable, and searchable** - without retraining.

Published on PyPI: [https://pypi.org/project/devmcp-context/](https://pypi.org/project/devmcp-context/)

## The Problem

AI agents are black boxes. You can't see what they remember. When they forget something important or remembers something wrong, you're stuck.

**devmcp-context changes this.** Your agent's memory is now:
- **Visible** - Plain text files in your project folder
- **Editable** - Change any entry, agent sees it immediately  
- **Structured** - Organized into 5 categories with automatic cleanup
- **Persistent** - Survives across agent sessions and restarts
- **Recall-first** - Memory loads automatically at session start

## Installation

```bash
pip install devmcp-context
```

Or with uv:

```bash
uv add devmcp-context
```

## Quick Start

```bash
cd your-project
devmcp-context init
```

That's it. This scaffolds `ai-context/` and configures your MCP client automatically. Supports opencode, Cursor, and Claude Desktop - auto-detected from your project.

For multiple projects, run `init` in each project directory. Each gets its own config entry:

```bash
cd ~/projects/todo-app && devmcp-context init
cd ~/projects/blog && devmcp-context init
```

**Manual setup** (if auto-detection doesn't work):

```bash
devmcp-context init --client opencode   # or cursor, claude
devmcp-context init --name my-context   # custom entry name
```

## Features

- **Auto-recall at session start** - project + decisions memory loaded automatically, compact index of everything else
- 5 memory categories (project, decisions, errors, tasks, ephemeral)
- **Outcome tracking** - `what_worked` and `what_failed` fields for decisions and errors
- **Superseded entries** - redirect recall to newer entries instead of deleting history
- **Key fact first** - entry summaries lead with the most important line
- Automatic expiration (TTL) - errors expire in 30 days, tasks in 14
- Full-text search across all entries
- Tagging system for organization
- Persistent file-based storage (no database)
- Session recall metric - tracks whether memory was used before edits
- MCP-compliant server

## Documentation

Full docs: [https://kushal1o1.github.io/devmcp-context/](https://kushal1o1.github.io/devmcp-context/)

- Getting Started guide
- Installation instructions
- API Reference (8 tools)
- Memory categories explained
- Architecture diagrams (Mermaid)
- Deployment guide
- Development guide

## Usage Example

In your agent prompt:

```
Agent calls context_session_start first to load memory.

Use context_save to remember insights:
- save("decisions", "auth_strategy", "Use JWT with refresh tokens",
       tags=["security"],
       what_worked="Stateless, scales horizontally",
       what_failed="Token refresh is complex")

Use context_load to retrieve memories:
- load("decisions")

Use context_search to find specific memories:
- search("JWT")

Use superseded_by to redirect old entries:
- save("decisions", "new-auth", "Switched to OAuth2",
       superseded_by="old-auth")
```

## License

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

## Contributing

Contributions welcome! See [CONTRIBUTING.md](docs/contributing.md) for guidelines.
