Metadata-Version: 2.4
Name: meaning-fs
Version: 0.1.0
Summary: Semantic File Index for AI Agents
Author-email: Rodrigo Pires <rneto.pires@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Rodrigo Pires
        
        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.
        
Project-URL: Homepage, https://github.com/bozaah/meaning-fs
Project-URL: Documentation, https://github.com/bozaah/meaning-fs#readme
Project-URL: Repository, https://github.com/bozaah/meaning-fs
Keywords: ai,context,semantic,index,agents,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Dynamic: license-file

# Meaning

> Semantic File Index for AI Agents

A lean, text-based semantic layer that lives alongside your files, readable by any AI agent, requiring no external services or embeddings.

## The Problem

AI agents operating on codebases lack semantic context. They see files as paths and text, not as purposeful artifacts with relationships. This causes inefficient navigation, missed dependencies, and lost context between sessions.

## The Solution

**Meaning** adds a `.meaning/` directory to your project containing:

- `index.yaml` — Semantic records for all files (intent, tags, relationships)
- `schema.yaml` — Project-specific vocabulary and relationship types
- `config.yaml` — Exclusion patterns and settings

When you say "update how API responses are parsed," your AI agent can read the index and know exactly which files to touch.

---

**👉 [Get Started in 5 Minutes](QUICKSTART.md) 👈**

---

## Status

**Phase 5 Complete** — Status overview and semantic query ✅

- ✅ Core library (`meaning_core.py`) - 1,100+ lines, 54+ tests passing
- ✅ Inference engine (`meaning_inference.py`) - 612 lines, 32 tests passing
- ✅ **Status command** - Instant project overview with concepts, health metrics, and recent activity
- ✅ **Query engine** - Natural language semantic search (6 query types, <50ms response)
- ✅ Five Claude Code skills (`/meaning-init`, `/meaning-update`, `/meaning-validate`, `/meaning-review`, `/meaning-query`)
- ✅ Hook scripts for automatic tracking
- ✅ Dog-fooded on itself (33+ files indexed, 0 validation errors)

**Next:** PyPI packaging, external project testing

## Quick Start

### Installation

```bash
# Install from source (PyPI coming soon)
pip install git+https://github.com/bozaah/meaning-fs.git

# Or for development
git clone https://github.com/bozaah/meaning-fs.git
cd meaning-fs
uv venv && uv pip install -e ".[dev]"
```

### Initialize a Project

```bash
# Basic initialization (auto-detects project type)
meaning init

# With Claude Code integration
meaning init --install-hooks --with-skills

# Skip file scanning (just setup the structure)
meaning init --skip-crawl
```

### With Claude Code Skills

```bash
# In your project directory with Claude Code
/meaning-init              # Bootstrap .meaning/ with intelligent inference
/meaning-review            # Review and approve suggested metadata
/meaning-validate          # Check index health

# During development
/meaning-update            # Sync with filesystem changes
/meaning-query             # Semantic search
```

## Discovering Your Project

Once initialized, instantly understand your codebase with zero latency:

```bash
# Get instant overview (concepts, health, recent activity)
python -m meaning status

# Natural language semantic search
python -m meaning query "what tests the core?"
python -m meaning query "show me all config files"
python -m meaning query "files that do parsing"
python -m meaning query "what needs review?"
python -m meaning query "what changed recently?"
```

**Example output:**
```
🔍 Query Results: Files that tests src/meaning/meaning_core.py
   Type: relationship

  Found 1 file (showing 1):

  1.   tests/test_core.py
      "Comprehensive test suite for core data structures..."
      Tags: test, module
      Relationships: tests(1), imports(1)
```

Or use the skill in Claude Code:
```bash
/meaning-query what tests the inference engine?
```

**6 Query Types Supported:**
- **Status**: "what needs review?", "what is stale?"
- **Tag**: "show me all test files", "find config files"
- **Relationship**: "what tests X?", "what documents Y?"
- **Intent**: "files that do parsing", "files about auth"
- **Temporal**: "what changed recently?"
- **Concept**: "show me the core library"

## Features

- **Instant Discovery** - `status` command shows project overview in <50ms
- **Semantic Query** - Natural language search across 6 query types (status, tag, relationship, intent, temporal, concept)
- **Intelligent Inference** - Automatically suggests tags, intents, and relationships with confidence scores
- **85-90% Time Savings** - Review AI suggestions instead of writing metadata from scratch
- **Git-Friendly** - Human-readable YAML files that diff and merge cleanly
- **Zero Dependencies** - Works offline, no external services or embeddings
- **Batch Review** - Efficient workflows for reviewing many files at once
- **Claude Code Integration** - Automatic tracking via hooks on file changes
- **Transparent** - All suggestions show confidence levels and reasoning
- **Non-Destructive** - Human reviews and approves all changes

Note: intent auto-accept uses Python module docstrings, markdown first paragraphs, and known filename/path patterns (README/CHANGELOG, templates, agent session notes). Files without these signals may remain `needs_review`.

## How It Works

### File Entries

Each file gets a semantic record:

```yaml
- path: src/api/parser.py
  intent: "Transforms raw API JSON responses into domain models"
  tags: [api, parsing, transforms]
  status: active
  relationships:
    - type: transforms
      source: src/api/client.py
      target: src/models/api_models.py
```

### Concepts

Related files are grouped into concepts:

```yaml
concepts:
  - name: api-parsing
    description: "External API response handling"
    files:
      - src/api/client.py
      - src/api/parser.py
      - src/models/api_models.py
    entry_point: src/api/parser.py
```

### Claude Code Integration

Meaning includes hooks for Claude Code that automatically track file changes:

```json
{
  "hooks": [
    {
      "matcher": { "type": "PostToolUse", "tool_name": ["write_file"] },
      "script": ".meaning/scripts/meaning-post-write.sh"
    }
  ]
}
```

Install hooks with:

```bash
python -m meaning init --install-hooks
```

## Philosophy

```
Do not write code before stating assumptions.
Do not claim correctness you haven't verified.
Do not handle only the happy path.
Under what conditions does this work?
```

## Project Structure

```
meaning/
├── .agent-sessions/            # AI agent session notes
├── .claude/                    # Claude Code configuration
│   ├── settings.json           # Project hooks and permissions
│   └── skills/                 # Skill definitions
│       ├── meaning-init/
│       ├── meaning-query/
│       ├── meaning-review/
│       ├── meaning-update/
│       └── meaning-validate/
├── .meaning/                   # Dog-fooding: our own semantic index
├── src/
│   └── meaning/
│       ├── __init__.py         # Public API exports
│       ├── __main__.py         # CLI entry point
│       ├── meaning_core.py     # Core library
│       ├── meaning_inference.py # Inference engine
│       ├── installer.py        # Installation logic
│       └── templates/          # Project templates
│           ├── schema/         # Project-type schemas (python, node, rust, docs, mixed)
│           ├── skills/         # Claude Code skill templates
│           ├── config.yaml     # Default config
│           ├── hooks.json      # Claude hooks template
│           └── scripts/        # Hook scripts for target projects
├── scripts/
│   ├── meaning-post-write.sh   # Post-mutation hook
│   ├── meaning-validate.sh     # Session-end hook
│   ├── run-inference.py        # Inference runner script
│   └── validate-meaning.sh     # Validate this project's index
└── tests/
    ├── fixtures/               # Test fixtures
    ├── test_core.py            # Core library tests
    ├── test_inference.py       # Inference engine tests
    └── test_installer.py       # Installer tests
```

## Documentation

- **[Quick Start Guide](QUICKSTART.md)** — Get started in 5 minutes
- [Implementation Plan](IMPLEMENTATION-PLAN.md) — Full specification
- [CLAUDE.md](CLAUDE.md) / [AGENTS.md](AGENTS.md) — Guide for AI agents working on this project
- [Agent Sessions](.agent-sessions/) — Session notes documenting project evolution

## License

MIT
