agent-property-inventory

agent-property-inventory is a local evidence ledger for physical possessions, exposed through a CLI and an MCP server for AI agents.

It records individual objects, where they are, their condition, the interfaces they use, and the evidence behind each claim. It is built for questions such as "Do I already own a T25 bit?", "Will this adapter fit?", and "What should go in this moving box?"

I built it because I wanted a durable way to record and query what I physically own, and to stop buying duplicates.

See it answer a real question

This exact block is reproduced from a temporary inventory by check-readme-example.py, which the CI workflow runs against the real CLI.

$ property-inventory search "T25" --summary
{
  "matching_record_found": true,
  "count": 1,
  "matches": [
    {
      "name": "T25 Torx bit",
      "ownership": "confirmed",
      "condition": "working",
      "location": "Tool drawer",
      "last_physical_check_on": "2026-08-09",
      "evidence_types": [
        "physical_check"
      ]
    }
  ],
  "next_cursor": null,
  "page_count": 1,
  "truncated": false
}

The item is a distinct physical unit, current possession was confirmed in person, its condition is working, and its last known location is the tool drawer. A search with no match returns unknown, not absent; it never turns a missing record into a claim that you do not own something.

Related MCP server: local-evidence-mcp

What you can ask

The same queries are available to agents through the local stdio MCP server.

How it works

1. Capture a fact. A person shows an object or checks a label, serial number, measurement, receipt, condition, or location. Every claim keeps its evidence.

2. Match before adding. The agent searches the existing inventory first. A known unit is updated; a genuinely different physical unit gets a new record.

3. Commit through the CLI. Canonical writes take one lock, create a backup, stage the complete change, rebuild the views, and run semantic and foreign-key checks. The live JSONL changes only after every check passes.

4. Query through the CLI or MCP. Reads use the same schema and scope rules. Read-profile MCP tools query the inventory. Write-profile tools prepare a proposal for review; the separate CLI command proposal-apply commits it.

The canonical write path is:

lock -> backup -> stage -> rebuild -> render -> verify -> replace

Data/store/*.jsonl is the source of truth. SQLite and the Markdown catalogue are generated views and can be rebuilt.

What it refuses to guess

Unknown serial numbers, locations, measurements, quantities, and compatibility facts stay unknown.

Where the files live

An installation keeps four paths separate:

The code can live anywhere. The private JSONL does not need to sit in an Obsidian vault.

Quick start

Python 3.11 or newer is required.

git clone https://github.com/Anneo22/agent-property-inventory.git
cd agent-property-inventory
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev,mcp]'

demo_root="$(mktemp -d "${TMPDIR:-/tmp}/property-inventory-demo.XXXXXX")"
export PROPERTY_INVENTORY_ROOT="$demo_root/inventory"
export PROPERTY_INVENTORY_RUNTIME="$demo_root/runtime"
export PROPERTY_INVENTORY_MEDIA_ROOT="$demo_root/media"
export PROPERTY_INVENTORY_CATALOGUE_OUTPUT="$demo_root/notes/Inventory.md"

property-inventory init
property-inventory status --summary

status rebuilds every generated view and runs the full integrity gate. Run property-inventory --help for the complete command surface.

Record the first item

For a direct check, the CLI caller supplies what was physically observed. A person or an agent acting on explicit observations runs discover to record the physical check, current possession, condition, quantity, and location in one verified transaction:

property-inventory add-location \
  --location-id loc-tool-drawer \
  --name "Tool drawer" \
  --kind container

property-inventory discover \
  --actor "Owner" \
  --source-ref "Checked in person" \
  --name "T25 Torx bit" \
  --category tool \
  --checked-on "$(date +%F)" \
  --location-id loc-tool-drawer \
  --new-model \
  --new-unit \
  --brand Wera \
  --model T25 \
  --quantity 1 \
  --unit piece \
  --condition working

property-inventory search "T25" --summary

For an item that may already exist, search first and use --existing-model-id or --existing-item-id. --new-unit is an explicit assertion that this is a different physical object.

Connect an agent

The MCP server runs locally over stdio. This example gives an agent read-only access to personal-scope data:

{
  "command": "/absolute/path/to/property-inventory-mcp",
  "args": [
    "--config", "/absolute/path/to/config.json",
    "--instance", "private",
    "--scope", "personal",
    "--profile", "read"
  ]
}

Write-profile MCP tools can create a proposal in private scope, but they cannot change canonical JSONL. The CLI caller decides what becomes fact: inspect the returned ID with property-inventory proposal-show <proposal-id>, check the proposed identity, quantity, condition, location, and evidence, then commit it with property-inventory proposal-apply <proposal-id>.

A photo follows the same boundary:

photo -> prepare_overview_capture -> confirm or correct observations
      -> review_overview_capture -> proposal-show -> proposal-apply

The agent passes a local image path and explicit crop regions to prepare_overview_capture. An optional adapter, selected from configuration fixed when the MCP server starts, can suggest regions and observations. Without an adapter, the caller supplies regions and manual observations. The tool stages the original and crops, then returns a digest plus any bounded suggestions and duplicate candidates. The caller confirms or corrects identity, quantity, condition, and location; review_overview_capture binds those decisions and the evidence to that exact image. Only the final CLI command changes the canonical inventory.

The CLI is the write-authority boundary: any person or agent given local CLI and filesystem access can invoke a direct write or proposal-apply. Direct commands such as discover have no separate proposal review, but still pass the full integrity gate before commit. An agent given only MCP access cannot bypass the proposal gate. See MCP profiles and overview capture.

Current limits

This is a local, single-user project. It has no graphical app, hosted service, built-in recognition model, or insurer integration. Photo and barcode adapters can propose observations, but nothing becomes an inventory fact until it is reviewed and committed through the CLI.

Documentation

Architecture · Schema · Operations · MCP · Capture · Threat model

License

MIT. See LICENSE.