Skip to main content

SimpleContext

Persistent memory for Claude Code via MCP – Store and recall context across conversations.

Version: 1.0.0 | Status: Production Ready | License: MIT


What is SimpleContext?

SimpleContext gives Claude Code the ability to remember information across conversations using 6 simple memory tools.

The Problem:

You: "We're using PostgreSQL with the user table in the auth schema"
(2 hours later)
You: "What database are we using?"
Claude: "I don't have that information..."

The Solution:

You: "Remember we're using PostgreSQL 14 on port 5432"
Claude: ✓ Remembered: Using PostgreSQL 14 on port 5432

(Later...)
You: "What database are we using?"
Claude: Found 1 memories: Using PostgreSQL 14 on port 5432

Features

✅ 6 Core Memory Tools

  • remember(content, tags) - Store information
  • recall(query) - Search with smart recency ranking
  • forget(query) - Delete memories
  • store(name, content) - Save large artifacts
  • retrieve(name) - Get artifacts back
  • status() - View system status

✅ Smart Features

  • Full-text search with FTS5
  • Temporal decay (recent memories ranked higher)
  • Secure storage (owner-only permissions)
  • Input validation and error handling
  • Sensitive data detection warnings

✅ Lightweight & Fast

  • 630 lines of Python code
  • SQLite backend (no external dependencies)
  • 7/7 tests passing

Requirements

  • Python 3.10+ (required for FastMCP)
  • Claude Code CLI installed

Check your Python version:

python3 --version  # Must be 3.10 or higher

Installation

# Clone the repository
git clone https://github.com/jmartinmatias/simplecontext.git
cd simplecontext

# Run automated installer
./install.sh
# Checks Python version, installs dependencies, runs tests

Manual Install

# Clone the repository
git clone https://github.com/jmartinmatias/simplecontext.git
cd simplecontext

# Install dependencies
pip install -r requirements.txt

# Run tests to verify installation
pytest tests/
# Expected: 7 passed in ~0.15s

2. Configure Claude Code

Add SimpleContext to your MCP configuration file at ~/.claude/.mcp.json:

{
  "mcpServers": {
    "simplecontext": {
      "command": "python3",
      "args": ["/absolute/path/to/simplecontext/src/simplecontext.py"],
      "cwd": "/your/working/directory"
    }
  }
}

Important: Replace /absolute/path/to/simplecontext with the actual path where you cloned the repo.

3. Restart Claude Code

# Restart Claude Code to load the MCP server
# The simplecontext tools will now be available

Usage Examples

Basic Memory Storage

You: "Remember we're using PostgreSQL 14 on port 5432"
Claude: ✓ Remembered: Using PostgreSQL 14 on port 5432 (ID: abc-123)

You: "Remember our API key is stored in AWS Secrets Manager"
Claude: ✓ Remembered: API key is stored in AWS Secrets Manager
⚠️  WARNING: Content may contain credentials or sensitive data!

Searching Memories

You: "What database are we using?"
Claude: [Automatically calls recall("database")]
Found 1 memories:
- Using PostgreSQL 14 on port 5432 (0d ago)

Storing Large Artifacts

You: "Store this config file as 'database.yml'"
Claude: ✓ Stored artifact: database.yml (2,048 bytes)

You: "Retrieve the database config"
Claude: [Returns full config file content]

Checking Status

You: "What's in memory?"
Claude: [Calls status()]
SimpleContext Status:
- Memories: 12
- Artifacts: 3
- Unresolved Errors: 0
- Current Mode: coding
- Database: .simplecontext.db

Architecture

simplecontext/
├── src/
│   ├── simplecontext.py    # MCP server (main entry point)
│   ├── memory.py           # Core memory operations
│   ├── storage.py          # SQLite backend + FTS5
│   ├── errors.py           # Error tracking
│   └── modes.py            # Context mode detection
├── tests/
│   └── test_simple.py      # 7 comprehensive tests
├── examples/
│   └── demo.py             # Working demo
├── requirements.txt        # Python dependencies
└── pyproject.toml          # Package configuration

Total: ~630 lines of code


Security Features

🔒 Built-in Security

  • Database files created with 0o600 permissions (owner-only)
  • Input validation on all tools (max 100KB per memory)
  • Sensitive data detection (warns if passwords/API keys detected)
  • Comprehensive error handling (prevents crashes)
  • SQL injection protection (parameterized queries)

How It Works

1. Storage

  • All memories stored in SQLite database (.simplecontext.db)
  • Full-text search using SQLite FTS5 extension
  • Automatic schema creation on first use

2. Temporal Decay

  • Recent memories ranked higher in search results
  • Recency score calculated based on age
  • Helps surface relevant, recent information first

3. Mode Detection

  • Coding mode: Focus on memories and artifacts
  • Debugging mode: Include recent errors in context

Configuration

SimpleContext works out of the box with sensible defaults:

Setting Default Description
Database path .simplecontext.db SQLite database location
Max content 100 KB Maximum memory size
Max query 1 KB Maximum search query length
Max artifact 1 MB Maximum artifact size
Recall limit 5-100 Results per search

Troubleshooting

"No module named 'mcp'" or "No module named 'fastmcp'"

Solution:

# Make sure you have Python 3.10+
python3 --version

# Install dependencies
pip install -r requirements.txt

"Tests failing"

Solution:

# Run tests with verbose output
pytest tests/ -v

# All 7 tests should pass
# If any fail, please file an issue on GitHub

"Claude doesn't see my memories"

Solution:

  • Verify MCP configuration in ~/.claude/.mcp.json
  • Check that paths are absolute (not relative)
  • Restart Claude Code after configuration changes
  • Claude must explicitly call recall() to search memories

"Permission denied" when accessing database

Solution:

# Check database file permissions
ls -la .simplecontext.db

# Should show: -rw------- (600)
# If not, fix permissions:
chmod 600 .simplecontext.db

Development

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Run specific test
pytest tests/test_simple.py::test_remember_recall -v

Project Structure

  • src/ - Main source code
  • tests/ - Test suite (pytest)
  • examples/ - Usage examples
  • docs/ - Additional documentation

Contributing

We welcome contributions! Please:

  • Keep changes focused and simple
  • Add tests for new features
  • Follow existing code style
  • Update documentation

Not accepting (to maintain simplicity):

  • Alternative storage backends
  • UI/dashboard features
  • Complex integrations

FAQ

Q: Does this work with other AI tools besides Claude Code? A: SimpleContext is designed specifically for Claude Code's MCP (Model Context Protocol). It may work with other MCP-compatible tools but is not officially supported.

Q: Where is data stored? A: All data is stored locally in .simplecontext.db in your working directory. Nothing is sent to external servers.

Q: Can I use this in production? A: Yes! Version 1.0.0 is production-ready with comprehensive security features and error handling.

Q: How much data can I store? A: Individual memories are limited to 100KB, artifacts to 1MB. Total database size is limited only by available disk space.

Q: Is my data encrypted? A: The database file has secure permissions (owner-only access), but data is not encrypted at rest. For sensitive data, consider using OS-level encryption.

Q: Can I migrate data between projects? A: Yes, the .simplecontext.db file is portable. Copy it to your new project directory.


Changelog

See CHANGELOG.md for version history and detailed changes.

Version 1.0.0 (Latest)

  • Production-ready release
  • Comprehensive security hardening
  • Input validation and error handling
  • Sensitive data detection
  • Database permission fixes (0o600)
  • Python logging integration
  • Full packaging support (pyproject.toml)

License

MIT License - See LICENSE file for details.


Support


Acknowledgments

Built with Claude Code and focused on simplicity, reliability, and production-readiness.

Core Technologies:

  • Python 3.10+
  • SQLite with FTS5
  • FastMCP (Model Context Protocol)
  • pytest

SimpleContext v1.0.0 - Persistent memory for Claude Code

Metadata

Release files for simplecontext 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for simplecontext 1.0.0
File Size Uploaded Provenance Actions
simplecontext-1.0.0.tar.gz 13.7 kB Without provenance Details for simplecontext-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for simplecontext 1.0.0
File Interpreter ABI Platform Actions
simplecontext-1.0.0-py3-none-any.whl Python 3 none any Details for simplecontext-1.0.0-py3-none-any.whl

Total release size: 28.4 kB

Release files / simplecontext-1.0.0.tar.gz

Download URL simplecontext-1.0.0.tar.gz
Size 13.7 kB
Tags Source
SHA-256 checksum
How to use checksums
1d6bfd70fcb9d6287f34452c9a90d2490d8d281f254a3cd82fa780ff64a921b4
BLAKE2b-256 checksum
How to use checksums
24221564ca5c772914f7b272fd0e96e155762024f4c4b8c0c583de3368ed89f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Release files / simplecontext-1.0.0-py3-none-any.whl

Download URL simplecontext-1.0.0-py3-none-any.whl
Size 14.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
137fcc9f3726692367520bbb1d2d67286e647864f3d52566c0ca42fb4ec0cc18
BLAKE2b-256 checksum
How to use checksums
dd7837be58a1997c6811ef674b139b23ba94ebb844bf6bfd2886868bea1a61b8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Security for simplecontext 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page