Metadata-Version: 2.4
Name: claude-fafm-sdk
Version: 0.1.1
Summary: Portable, cross-vendor AI memory in .fafm — offline-first SDK; connect a free namepoint for full intel.
Project-URL: Homepage, https://memory.faf.one
Project-URL: Repository, https://github.com/Wolfe-Jam/claude-fafm-sdk
Project-URL: Format spec, https://github.com/Wolfe-Jam/faf
Project-URL: Voice profile (grok-faf-voice), https://pypi.org/project/grok-faf-voice/
Author-email: James Wolfe <team@faf.one>
License: MIT
License-File: LICENSE
Keywords: agents,ai,claude,cross-vendor,fafm,memory,portable
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.10
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: namepoint
Requires-Dist: fastmcp>=3.2; extra == 'namepoint'
Description-Content-Type: text/markdown

# claude-fafm-sdk

[![PyPI](https://img.shields.io/pypi/v/claude-fafm-sdk)](https://pypi.org/project/claude-fafm-sdk/) · [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) · [memory.faf.one](https://memory.faf.one)

**Portable, cross-vendor AI memory in `.fafm`.** Give an AI agent memory that
versions with your project and moves between models — instead of being locked to
one vendor.

Offline-first: the local `Soul` works with no account. Connect a free
**namepoint** for the full intel (semantic recall, smart-merge) at personal scale.

> **Two profiles, one `.fafm` format.** This is the **knowledge** profile (typed,
> cross-linked agent memory). For the **voice** profile — the Voice Memory Layer —
> see [grok-faf-voice](https://pypi.org/project/grok-faf-voice/).

## Install

```sh
uv add claude-fafm-sdk          # in a project (recommended)
pip3 install claude-fafm-sdk    # also works
```

## 30 seconds

```sh
uvx claude-fafm-sdk init                 # 🧬 create a portable soul
claude-fafm-sdk etch "ships uv-first"    # write a memory
claude-fafm-sdk recall uv                # recall it
```

Hand `soul.fafm` to `grok-faf-voice` and it reads it — same format, no fork.

## Quickstart

```python
from claude_fafm_sdk import Soul

soul = Soul("@me")
soul.etch("ships uv-first", id="install", type="reference", priority="high")
soul.etch("portable across vendors", id="why", type="project")
soul.save("me.fafm")            # → application/vnd.fafm+yaml

# later, anywhere:
soul = Soul.load("me.fafm")
soul.recall("uv")               # deterministic recall, ranked by priority + recency
```

That's the whole offline loop — no account, no server.

More in **[examples/](examples/)** — portability + a real cross-vendor roundtrip
(SDK writes `.fafm`, grok-faf-voice reads it back).

## Full intel (free namepoint)

A **namepoint** is a free handle on [memory.faf.one](https://memory.faf.one)
where your soul lives (hosted + sticky) and the full intel runs at personal scale.
Hosted reads/writes use the family-standard MCP client (`fastmcp`), an opt-in extra:

```sh
uv add "claude-fafm-sdk[namepoint]"
```

```python
from claude_fafm_sdk import Namepoint

np = Namepoint("@me", api_key="...")        # free key from memory.faf.one
await np.push("a durable fact", type="fact")
body = await np.pull()                       # reads are public — no key
```

Wired to the MCPaaS asset core — the same backend grok-faf-voice uses
(`get_soul` / `write_soul`). The `memory.faf.one` front door + free-namepoint
signup are landing; the local `Soul` works fully offline today, no account.

## Why

AI memory is vendor-locked. `.fafm` is the open, portable format — and this SDK
is the open, offline-first way to use it. Souls written here interop with the
`fafm-engine` and `grok-faf-voice` implementations: one format, never a fork.

## License

MIT. The format is open ([spec](https://github.com/Wolfe-Jam/faf)); the SDK is
open; the at-scale intel + hosting is the paid tier.
